Contributing

Setup

Fork django-oauth-toolkit repository on GitHub and follow these steps:

  • Create a virtualenv and activate it
  • Clone your repository locally

Issues

You can find the list of bugs, enhancements and feature requests on the issue tracker. If you want to fix an issue, pick up one and add a comment stating you’re working on it.

Pull requests

Please avoid providing a pull request from your master and use topic branches instead; you can add as many commits as you want but please keep them in one branch which aims to solve one single issue. Then submit your pull request. To create a topic branch, simply do:

  1. git checkout -b fix-that-issue
  2. Switched to a new branch 'fix-that-issue'

When you’re ready to submit your pull request, first push the topic branch to your GitHub repo:

  1. git push origin fix-that-issue

Now you can go to your repository dashboard on GitHub and open a pull request starting from your topic branch. You can apply your pull request to the master branch of django-oauth-toolkit (this should be the default behaviour of GitHub user interface).

When you begin your PR, you’ll be asked to provide the following:

  • Identify the issue number that this PR fixes (if any). That issue will automatically be closed when your PR is accepted and merged.
  • Provide a high-level description of the change. A reviewer should be able to tell what your PR does without having to read the commit(s).
  • Make sure the PR only contains one change. Try to keep the PR as small and focused as you can. You can always submit additional PRs.
  • Any new or changed code requires that a unit test be added or updated. Make sure your tests check for correct error behavior as well as normal expected behavior. Strive for 100% code coverage of any new code you contribute! Improving unit tests is always a welcome contribution. If your change reduces coverage, you’ll be warned by coveralls.
  • Update the documentation (in docs/) to describe the new or changed functionality.

  • Update CHANGELOG.md (only for user relevant changes). We use Keep A Changelog format which categorizes the changes as:

    • Added for new features.
    • Changed for changes in existing functionality.
    • Deprecated for soon-to-be removed features.
    • Removed for now removed features.
    • Fixed for any bug fixes.

    • Security in case of vulnerabilities. (Please report any security issues to the

      JazzBand security team security@jazzband.co. Do not file an issue on the tracker or submit a PR until directed to do so.)

  • Make sure your name is in AUTHORS.

If your PR is not yet ready to be merged mark it as a Work-in-Progress By prepending WIP: to the PR title so that it doesn’t get inadvertently approved and merged.

The repo managers will be notified of your pull request and it will be reviewed, in the meantime you can continue to add commits to your topic branch (and push them up to GitHub) either if you see something that needs changing, or in response to a reviewer’s comments. If a reviewer asks for changes, you do not need to close the pull and reissue it after making changes. Just make the changes locally, push them to GitHub, then add a comment to the discussion section of the pull request.

Pull upstream changes into your fork regularly

It’s a good practice to pull upstream changes from master into your fork on a regular basis, in fact if you work on outdated code and your changes diverge too far from master, the pull request has to be rejected.

To pull in upstream changes:

  1. git remote add upstream https://github.com/jazzband/django-oauth-toolkit.git
  2. git fetch upstream

Then merge the changes that you fetched:

  1. git merge upstream/master

For more info, see http://help.github.com/fork-a-repo/

Note

Please be sure to rebase your commits on the master when possible, so your commits can be fast-forwarded: we try to avoid merge commits when they are not necessary.

How to get your pull request accepted

We really want your code, so please follow these simple guidelines to make the process as smooth as possible.

Run the tests!

Django OAuth Toolkit aims to support different Python and Django versions, so we use tox to run tests on multiple configurations. At any time during the development and at least before submitting the pull request, please run the testsuite via:

  1. tox

The first thing the core committers will do is run this command. Any pull request that fails this test suite will be immediately rejected.

Add the tests!

Whenever you add code, you have to add tests as well. We cannot accept untested code, so unless it is a peculiar situation you previously discussed with the core committers, if your pull request reduces the test coverage it will be immediately rejected.

You can check your coverage locally with the coverage package after running tox:

  1. pip install coverage
  2. coverage html -d mycoverage

Open mycoverage/index.html in your browser and you can see a coverage summary and coverage details for each file.

There’s no need to wait for coveralls to complain after you submit your PR.

Code conventions matter

There are no good nor bad conventions, just follow PEP8 (run some lint tool for this) and nobody will argue. Try reading our code and grasp the overall philosophy regarding method and variable names, avoid black magics for the sake of readability, keep in mind that simple is better than complex. If you feel the code is not straightforward, add a comment. If you think a function is not trivial, add a docstrings.

The contents of this page are heavily based on the docs from django-admin2