Contributing to the repository

Implementing a Change

1. Make sure you're on the master branch. git branch -l If not, switch to the master branch. git checkout master
2. Pull the latest updates from master git pull origin master
3. Create a new branch named after the feature that you're implementing git checkout -b "my_new_feature"
4. Make the necessary changes, making sure to regularly commit with good commit messages.
5. Push the changes to github git push origin my_new_feature

Merging a Change

1. After pushing, check the main github page of the project and there should be an option to create a pull request from your recently pushed branch.

2. Make the pull request and give a brief description. If the pull request addresses an open issue (say, issue 4), add the text closes #4 to the body of the request, so that merging the pull request will also close the issue.

3. Let others to review and approve the pull request. This may require you to make new commits to the branch, which can be added to the pull request with git push origin my_new_feature. Eventually, the reviewer approves the changes (commenting on the pull request).

4. If your branch is clear to merge, there should be a big green button on the bottom of the page that lets you merge. You might have some merge conflicts, however, in which case the merge button will be red. To resolve this, get the latest changes on master (git pull origin master), then run git rebase master from your feature branch, resolve all conflicts, add conflicted files with git add, and continue the rebase with git rebase --continue.

5. Now, squash your changes into a single commit to keep the log clean. To do this, run git rebase -i HEAD~n, where n is the number of commits on your branch. This will give you an interactive editor, wherein you should leave the first (top-most, i.e. earliest) commit as 'pick', and change all subsequent commits to 'squash'. Save and exit, and you will be presented with another editor in which you can specify a commit message for all of your work.

6. Now push this change with git push -f origin my_new_feature.

7. Now you're ready to merge! If you don't get a green button that says you can merge, you've done something terribly wrong. Otherwise, merge with:

    git checkout master
    git merge my_new_feature
    git push origin master
   

and subsequently reload your pull request page (which should now say that it's merged) and push the "delete this branch" button to remove your remote feature branch.

8. Your local repo doesn't know that the remote branch has been deleted, so clean up state with:

    git checkout master
    git pull --prune origin
    git branch --merged | grep -v "\*" | xargs -n 1 git branch -d
   

9. All done!