GitHub Standard Operating Procedures

Introduction

PySAL went to the Pull Request model at the 2013 SciPy Conference. Basically this involves the following components.

• The organization GitHub account that has the master branch and dev branch

The master branch at upstream is to be in a production-ready state at all times.

The dev branch reflects a state where the latest delivered development changes for the next release reside. This is sometimes referred to as the integration branch.

When enough new features are incorporated into the dev branch, a rolling release is generated via a merge back into the master branch.

A high level overview of our model and these components is as follows. All work will be submitted via pull requests. Developers will work on branches on their local clients, push these branches to their GitHub repos and issue a pull request to the organization GitHub account. One of the other developers must review the Pull Request and merge it or, if there are issues, discuss them with the submitter. This will ensure that the developers have a better understanding of the code base and we catch problems before they enter dev.

Setting this all up is described in more detail below.

Initial Setup

• If you don't have one yet, create your own account on GitHub
• Fork pysal/pysal into your personal GitHub account
  • Article on forking
• On a laptop/desktop client, clone master from you GitHub account
  git clone https://github.com/sjsrey/pysal.git change sjsrey to yourUsername

Additional Resources for Setup

• http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup
• https://github.com/corranwebster/SciPy2013

Development

Say you want to work on one of the bugs or enhancements in PySAL.

On your local client proceed as follows:

1. Add an upstream remote repository pointing to the PySAL organization repos git remote add upstream https://github.com/pysal/pysal.git
2. Pull from upstream to get the latest dev git pull --rebase upstream dev
3. Create a branch on your client git branch bugfix where bugfix is the name you want to use for the branch.
4. Switch to this branch git checkout bugfix
5. Make your changes. Note that before doing a pull request (below) you also want to ensure that any changes that have been accepted upstream can be integrated with any changes you are making now. So be sure to git pull upstream dev into your working branch.
6. When you are happy with your changes run the tests on your client nosetests pysal/ where pysal is the toplevel directory of your code base in the branch. You need to be in the toplevel directory, so if you cloned into /home/user/code/pysal you need to run nosetest from within /home/user/code/pysal. If you also wish to run the code coverage tools instead run nosetests --with-coverage --cover-package=pysal. (nose-exclude is required to run the tests: pip install nose-exclude). If you have set up travis-ci.org testing like described in the next section, you can skip this step.
7. If the tests pass you can push the branch to the PySAL repository on your personal GitHub account
8. Check which files have been changed git status
9. Add the files that you want to go into a pull request with git add file1 file2
10. Commit your files git commit
11. Push your changes to your PySAL repos on GitHub git push origin bugfix

Automated Testing w/ Travis CI

TravisCI is a continuous integration framework used to test our codebase automatically. The upstream repo, pysal/pysal has Travis set up already. Getting travis set up for your personal fork allows you to have an automated testing framework to check if your personal changes on master are working correctly.

To setup Travis on your personal fork, first log in to Travis using your Github ID:

Then, once that's setup, edit the .travis.yml configuration file in the root of the project. To do this, open the file in a text editor. At the bottom, find the notifications section. It should look something like this:

notifications: 
    email: 
          - Alice@example.com
          - Bob@example.com

to get emails about the test status of your fork, add your name to the list by entering your email on a new indented line. So, if your email was Cindy@example.com, the new notifications section would look like this:

notifications: 
    email: 
          - Alice@example.com
          - Bob@example.com
          - Cindy@example.com

Then, add & commit the changes. When you push to your repo, you will have enabled the Travis CI integration, and will recieve emails about the status of your tests.

If you'd like to not notify other developers about your tests, you can remove emails from the section as well. If you'd like to get notifications whenever a developer starts a build, you can submit a pull request to add your email upstream.

Pull Request

• After you have pushed your branch up to your personal GitHub account, you can issue a pull request on GitHub. Details on how to do so are described here.
• If the pull request is closing an issue, include a comment with fixes #issue_number. This comment will close the issue when the pull request is merged. For more information see here
• Another dev will review your PR and either merge it, or provide you feedback. Do not merge your own PR as this way we can increase the review of code going into the project. If you have not received feedback on your PR in a timely fashion, feel free to assign a dev to review it or reach out to another dev to do so.
• If your pull request has been reviewed, merged and closed, your contributions will now be in the organization dev branch
• At this point on your client you can go ahead and delete the branch git branch -d bugfix
• You will also want to pull from the organization dev branch to have these changes reflected in your local (laptop/desktop) dev branch:
  • git checkout dev
  • git pull --rebase upstream dev
• Then push from your local client to your GitHub account git push origin dev
• At this point the three dev branches (one on organization, one on your GitHub account, and one on your client) are all in sync.
• Move on to the next feature or bug fix.