How we handle contributions

We use git/Github to handle contributions. If you're new to git, you may appreciate this guide.

As a contributor

Creating a pull request

Get the latest version of master

Before creating a pull request, update the master branch of your local repository with the latest version of the OpenHatch-owned repository. In git, you can achieve this by developing on a branch and rebasing your branch commits on top of master with git rebase master. You can also use git rebase -i master for an interactive rebase, in which you can reorder and edit commits. We prefer rebasing to merging because rebasing preserves a linear commit history, which can be easier to keep track of and reason about.

Test your changes

  1. Add unit tests with your functionality changes or additions.
  2. Use docstrings and comments where appropriate. Spell-check your additions. Try to apply pep8 standards.
  3. Test your changes on a local instance of the website. Prove to yourself that your changes address the issue they are supposed to address.
  4. Run the test suite, and make sure your unit tests pass and all tests that passed before your changes still pass.
  5. Use a tool like PyChecker to check for bugs.

Generate a pull request

Generate a pull request by pushing your changes to your personal remote. You can then create a pull request to the OpenHatch repository. In the commit message, include the issue the pull request addresses. For example: "Closes: http://openhatch.org/bugs/issue398"

Submitting a pull request

  1. Add a link to the pull request in the issue ticket at https://openhatch.org/bugs.
  2. Change the issue status to "need-review".
  3. Join IRC and say that you have an issue ready for review.

The pull request will be checked for code style errors (such as pep8 violations) by the lint-review bot. To know more about the bot, see Checking coding style errors in pull requests with lint-review.

If the reviewer says it's ready to go, your request will get merged in short order. If the reviewer has feedback he/she wants addressed, make the necessary revisions and start back at the "Check/test your changes" section.

Permit us to share your work

  1. Join our Devel email list by entering your email address into the form at http://lists.openhatch.org/mailman/listinfo/devel

  2. Send an email to devel@lists.openhatch.org with a message like:

    The work I contribute to OpenHatch is work I have permission to share. I permit anyone to re-use it under the terms of the Affero GPL, version 3 or later. Additionally, contributions in the docs/ directory can be shared under the terms of CC Zero 1.0.

As a reviewer

Apply the pull request to your local repository

Find the URL of the pull request by going to the main pull request page on Github and clicking on the link named 'command line'. Github will give you instructions, including the URL of the pull request. Follow all of the instructions except the last one, which tells you to push back to the origin.

Review the pull request for correctness and cleanliness

Things to think about:

  1. Does the pull request make sense? Does it look readable?:

    git log -p
    
  2. If the author hasn't already done this: tell the author "Please email devel@lists.openhatch.org saying that you're okay with your work being under the Affero GPL, version 3. If you're willing, it is preferable that you say 'the Affero GPL, version 3 or later, at your option'."

  3. If you have revisions you'd like to see made, change the issue status to "in-progress", re-assign the issue to the pull request submitter if it isn't already, and leave your review feedback on the pull request.

  4. After leaving the revisions in the comments, you may optionally leave a note to the author regarding expectations on when or if the pull request will be worked on further. You may use the below example:

    To add an arbitrary (but perhaps useful for planning) time
    bounded-ness, is this addressing the above something you'd be
    interested in doing over the next 3 days? If not, I can take care of
    it after that. If you're interested in being the one to do so, but you
    know you need more than 3 days is not long enough, that is fine; just
    say so, and we're happy to wait for you to perfect these changes.
    

Push and deploy

If you want to deploy the changes, and you have push access to the repository, you can do so by following the steps listed in the section labeled Deployment.

If you don't have push access, you will need to rope someone else in for this. Anyone in the Login team can do a push as well as deploy access. Asheesh Laroia (paulproteus) is the traditional person to do this, but it's good to ask someone else so they get practice!

Things to know:

  • If you push to origin/master, Travis CI will test it.

  • Once you're happy, you can run the deploy script, but note that will push the current HEAD to origin/master.

    cd mysite
    ./scripts/deploy
    
  • When you deploy, check a page or two to make sure things are okay.

For more details on how we use Continuous Integration and Travis CI, see Continuous integration.