Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
GitHub Standard Operating Procedures
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.
- Releases are made via tags out of master.
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
Setting this all up is described in more detail below.
- If you don't have one yet, create your own account on GitHub
- Fork pysal/pysal into your personal GitHub account
- On a laptop/desktop client, clone master from you GitHub account
git clone https://github.com/sjsrey/pysal.gitchange
Additional Resources for Setup
On your local client proceed as follows:
- Add an upstream remote repository pointing to the PySAL organization repos
git remote add upstream https://github.com/pysal/pysal.git
- Pull from upstream to get the latest master
git pull --rebase upstream master
- Create a branch on your client
git branch bugfixwhere
bugfixis the name you want to use for the branch.
- Switch to this branch
git checkout bugfix
- 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 masterinto your working branch.
- 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/pysalyou 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.
- If the tests pass you can push the branch to the PySAL repository on your personal GitHub account
- Check which files have been changed
- Add the files that you want to go into a pull request with
git add file1 file2
- Commit your files
- 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.
- 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
- 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
masterbranch to have these changes reflected in your local (laptop/desktop)
git checkout master
git pull --rebase upstream master
- Then push from your local client to your GitHub account
git push origin master
- At this point the three master 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.