Set Up Your Git Environment (for first-time contributors)

Make sure you have your basic Git environment set up.

Choose an Issue

Find a bug or feature you like; nail down your JIRA ticket; if necessary, file it in JIRA.

Design Your Solution

If you are developing a feature, or you are working on a bug that involves an interface change, you'll need to go through the design phase. 

Develop Your Solution

Update fork

Update your (forked & locally cloned) repository's master branch with the golden repository's master (IMPORTANT: Your fork's master branch should not be touched with any of your development changes. It should just reflect the golden repository's master, exactly).

Create dev branch

Create a development branch for the ticket that you would like to work on and name it with the JIRA ID of the ticket:

Check the checklist

Look at the checklist for developing code. 

Develop code and tests

We recommend developing your code and your tests in parallel.  Your PTL tests should provide good coverage of the requirements and your design.

Put license text in headers for code and tests

If you create new source or test files, make sure that this license text is in the header for all code and test files.

Commit-push cycle

• Commit changes in the updated file to your branch with a good commit message.  Make your commit message relevant and concise, so that it will be helpful to you later:

Tip: Commit often, perfect later.

• Push the development branch to your fork.  By convention,  'origin' points to your forked repository on GitHub:

• Repeat the above steps until you are satisfied with your code change.

Prepare for pull request

• Fetch changes made to the golden repository by other contributors.  By convention, 'upstream' points to the golden repository on GitHub:

• Rebase your development branch with new changes from the golden repository's master. 'upstream/master' is the remote tracking branch for the golden repository's (upstream's) master branch, on your local machine:

• If there are conflicts, Git will throw an error message informing you so and ask you to resolve it before continuing the rebase.  Resolve conflicts the same way you resolve an ordinary merge conflict in Git. Here's a way to resolve conflicts from the command line.  Then, just continue the rebase operation:

• If the conflict is complex or problematic, you can abort the current rebase operation instead of continuing, and come back to it later:

• After the rebase is complete, you might want to clean up your branch's commit history:
• Squash all your commits into fewer, meaningful change commits (just one suffices if the code change is small enough).

• Write meaningful commit messages for your commits while doing the squash above. You can also use git commit --amend or rebase if you'd rather do it later.

• Finally, push the polished branch to your fork. Because you did a git rebase, you'll need to do a force push.

Create Pull Request

Your code changes are good to go! Go ahead and create a pull request.

Get Approval for Your Code and Tests

Your code is ready to be merged into the golden repository when the following are true:

• The code adheres to our coding standards
• You have approval from two people: one maintainer and one other contributor (who can be a maintainer); approvals for code and tests happen on GitHub inside pull requests, not the wiki

Review and Check In

Clean Up

• Housekeeping: we strongly recommend that you delete the development branch from your forked and cloned repos now.

Update Your Issue

Update the issue on which you were working.