Contributor Workflow - Code/Docs

Submit a change for Code or Documentation in Git

Prerequisites

• Have you signed an Apache ICLA? See: project On-boarding
• Do you have a GitHub account? See: development tools

Command-line instructions here assume you have "hub" installed. If you do not use "hub", you should be able to accomplish the same thing using the github.com web site plus some git commands. You can alias "git" to "hub" for ease of use, but here we'll use "hub" explicitly for clarity. Instructions below use GHuser in place of your github username.

Initial Steps (need not be repeated for subsequent changes)

1. Clone the trafodion repo from the GitHub mirror
   • git clone git@github.com:apache/incubator-trafodion   ## using ssh

OR

1. • hub clone -p apache/incubator-trafodion                      ## -p option for ssh
2. Fork the repo on github , if you have never done so.

• • cd incubator-trafodion

Then:

• • hub fork

OR

• • Use "Fork" button on web (https://github.com/apache/incubator-trafodion)
  • git remote add GHuser git@github.com:GHuser/incubator-trafodion

Create a Task Branch

1. Make sure you have the latest changes
   • git fetch --all
2. Base your branch on the latest master
   • git checkout -b MyBranch origin/master

Make Changes

• Edit, Build, Test, Repeat
• You may make multiple local commits as desired. Unlike the Gerrit tool, you do not need to keep your changes in a single commit.
• Depending on how long you work on the changes you may want to rebase your branch, using git rebase.
• Prior to pushing your changes to github, you may use git commands that alter your branch history:
  • commit --amend, rebase, merge --squash

If you are making changes to the SQL engine, you'll want to run the developer regression tests in your workspace before committing. Instructions on how to do that can be found here: https://wiki.trafodion.org/wiki/index.php/Test_Suites

Push Changes to your GitHub Fork

1. Push the branch to your github repo, specifying the branch (or HEAD) to push. The remote is named the same as your github user ID (created earlier by "hub fork" or "git remote add...").
   1. git push -n GHuser HEAD           ## dry-run option to check
   2. git push GHuser  MyBranch
2. Once you publish your changes in this way, you should not subsequently use git commands that alter your branch history:
   • commit --amend, rebase, merge --squash

Create a Pull Request

1. Request your branch to be pulled to apache/incubator-trafodion
   • hub pull-request
2. Be sure to include the JIRA ID in brackets at the beginning of the title of your pull request (PR). This allows all activity on the PR to be mirrored to Jira.
   • [TRAFODION-12345] Cool Feature Xyz
3. Automated tests are normally triggered to run on every pull request. If you are modifying something that will not affect testing, you can add a phrase to the comments of the pull request:
   • jenkins, skip test

Update your Pull Request

1. Follow the github conversation on your pull request and respond to questions and issues. You should be automatically subscribed to your own pull requests.
   • To make additional changes, go to your local working branch and make additional commits. Do NOT use --amend.
   • git checkout MyBranch ; <edits, etc> ; git commit
2. Push the branch to your github fork. These changes automatically show up in the pull-request.
   • git push GHuser  MyBranch

Checking Test Results

Automated tests take at least a couple hours from when your pull-request was okay'd by a project member or updated with a new commit.

Normally, the Traf-Jenkins user will post a message in the pull-request with a link to the results. But you can check the Jenkins server to see the status even before the tests are finished. Look in the "Build History" table for the build/test job that matches your pull-request: 

"https://jenkins02.trafodion.org/job/Check-PR/"

One way to look at logs :

1. The first two columns in build-job table are links to the specific sub-job, so you can drill down there.
2. The console log of each job has a link to the log file directories (about 7 lines from the top). Look carefully for "Detailed logs".

Another way to look at logs :

1. The location of the logfiles is much more predictable than it used to be.
2. You can go to http://logs.trafodion.org/PullReq/
3. Click on the number of the pull request, such as http://logs.trafodion.org/PullReq/18/. The next directory level is the build number. With multiple commits or re-tests, it is possible for a pull request to have multiple builds.
4. Under that, there is a directory for each specific job, such as http://logs.trafodion.org/PullReq/18/35/regress-seabase-ahw2.2/

Change Merged

1. If all is well, a committer will merge your change into the Apache repo, which is mirrored on github.
2. You may be asked to close out the JIRA or other follow up.
3. Yea! Thanks for your contribution to Trafodion.

Related articles