Git Workflow

The basic git workflow is that developers should fork the repository and develop in feature branches, then send pull requests to the main nanograv/PINT github repository. Some useful commands for doing that are documented here.

Set up forked repository

• Fork the nanograv/PINT repository with the github web interface and check it out to your local machine with git clone
• Set up upstream tracking of the main repo with this command (the upstream repo will be called nanograv):
• git remote add nanograv https://github.com/nanograv/PINT.git

To update local master with nanograv/master

• git fetch nanograv
• git checkout master
• git merge nanograv/master

Add a feature branch

• git branch my_feature
• git checkout my_feature
• [edit files]
• Note that while you are editing your feature, it is best not to push your feature branch up to github
• git commit # Make sure you use useful commit messages.
• Repeat, keeping each commit as a relatively small and atomic change, in case individual commits need to be adjusted or rejected by the maintainer during the merge process.
• Do not commit local changes to setup.py. Stash those if needed.

When you are ready to merge your changes with nanograv/PINT

• First, make sure that the test suite run-tests.sh runs without error. Fix any issues
• Update your master with nanograv/master as described above
• Rebase your feature onto the master, and resolve any conflicts. This way the person contributing a feature is responsible for making sure it works with the main branch. If, as recommended, you have not pushed your branch to github, this all happens locally and will result in a nice linear commit history.
• git checkout my_feature
• git rebase master
• Edit the CHANGELOG to briefly describe new features or API changes included in your branch
• Then push to github and set the local and remote branches to track one another
• git push -u origin my_feature
• At this point, you can do a pull request
• If any changes are requested by the nanograv maintainer, make additional commits and git push. These will get added to the pull request
• When the pull request is merged by the maintainer, delete your feature branch locally and on github
• git branch -d my_feature
• git push origin --delete my_feature