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 ( The project does *not* make use of MIT's 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, 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

(If you're using SSH keys to authenticate to Github, you would do use 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: (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: 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.