Working With Github

We rely heavily on Github for our workflow, because it makes code review easier and provides an easily viewable history of changes, pull requests, etc.

NOTE: As of this writing (July 2015), we only use "regular" Github (github.com). The project does *not* make use of MIT's github.mit.edu service, with the single exception of adding a remote for the moira repository to fetch changes from. (described elsewhere)

If you don't have a Github account, go create one now. The rest of this document assumes that you have a Github account, and can authenticate to it from your Git client, whether using SSH keys, passwords over SSL/webdav, or some other means.

Forking Projects

In preparation for working on a project, you should log in to Github's web interface, find the project under https://github.com/mit-athena/whatever, and fork it into your Github account.

In your checkout of the Athena source tree, change to the project's directory, and add your fork as a remote. A common convention is to use your username as the remote name. This example assumes your username is jdreed and your Github username is also jdreed:

jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git remote add jdreed https://github.com/jdreed/getcluster

(If you're using SSH keys to authenticate to Github, you would do use git@github.com:jdreed/getcluster.git as the URL instead.)

Pushing and Pull Requests

When you commit your changes, you should push them to *your* fork.

jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git commit -a -m 'Fix awesome bugs'
jdreed@infinite-loop:~/src/athena-source-tree/athena/getcluster$ git push jdreed master

Then, visit you fork on Github's website, and submit a Pull Request from your branch. If your pull request contains multiple commits, write a summary of it in the field provided. If it only contains a single commit, it will be pre-populated from the commit message.

That will take you to a URL like this: https://github.com/mit-athena/getcluster/pull/1 (SEE IMPORTANT WARNING BELOW )

You can comment on others' pull requests, and they will comment on yours. When the pull request receives one more "+1"s, you can return to your checkout of the source tree, and push your changes to origin, as described in this page.

WARNING

WARNING: NEVER, EVER, EVER, EVER click the big green "Merge" button on a Pull Request page on Github. That will cause our synchronization scripts to break.