Contributor Workflow - Code/Docs

This page describes the contributor workflow for changes to Trafodion code and documentation.  To contribute to the wiki, see Contribute to the Wiki.

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 can 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)

Clone the Trafodion Repository from the GitHub Mirror

If you are using ssh:

git clone git@github.com:apache/incubator-trafodion

hub clone -p apache/incubator-trafodion  ## -p option for ssh

Fork the Repository on GitHub, If Needed

If you've never forked the repository on GitHub, then do the following.

cd incubator-trafodion
hub fork

Alternative method.

1. Use the Fork button on the web interface: https://github.com/apache/incubator-trafodion

2. Execute the following command: git remote add GHuser git@github.com:GHuser/incubator-trafodion

Create a Task Branch

# Ensure that you have the latest changes.
hub fetch --all
# Base your branch on the latest master.
hub checkpout -b <mybranch> orgin/master

Make Changes

Once you have created your task branch, you are ready to make changes.

To make changes to the documentation:

• <tbd - place holder to describe how to make changes to documentation>

To make changes to the code:

• Perform the build as described in Building the Software (Under construction ....)
• Make your changes, build, and test.  Repeat until you are ready to commit.

Once your changes are completed:

• Commit your change
• You may make as many multiple local commits as desired. 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 code, you'll want to run regression tests in your workspace before committing. Instructions on how to do that can be found here: 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. However, if your github ID is not on the contributor list your request has to be okay'd by a project member before tests start. 
4. If you are modifying something that will not affect testing such as updating documentation, 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

Check Test Results

Automated tests take several hours to complete 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. For instance master branch tests are at "https://jenkins.esgyn.com/job/Check-PR-master/"

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 (close to the top). Look 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://traf-logs.esgyn.com/PullReq/
3. Click on the number of the pull request, such as http://traf-logs.esgyn.com/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://traf-logs.esgyn.com/PullReq/18/35/regress-seabase-ahw2.2/

The check tests do not include all of the automated daily tests. If you (or another contributor) want, you can run additional tests on the pull request.

More information about the automated test set-up.

Merge changes

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