We <3 contributions; please feel free to check out the code! In general, this is a quick overview of how to contribute to DJOAuth2 using the standard Github pull-request flow. For more information, Github has a nice overview here.
Fork and clone the repository¶
The first step of contributing is creating your own copy (“fork”) of the main DJOAuth2 repository. Do this through the Github web interface:
Now that you have a copy, copy the “SSH clone URL” from the right-most column:
and run the following commands from a local terminal:
cd ~ # The email@example.com URL is the "SSH clone URL" that you copied. git clone firstname.lastname@example.org:<YOUR_USER_NAME>/djoauth2.git cd djoauth2
We rely on virtualenv for managing dependencies in order to make it as easy as possible to start contributing. Before contributing, run the following commands:
# Install development dependencies inside a new virtualenv make dev-env # Activate the virtualenv so that you have access to the dependencies that # were installed. . dev-env/bin/activate
After setting up your virtualenv, check out a new branch locally:
git checkout -b 'my-feature-branch'
Now make your changes. Don’t forget to update the tests! Please follow our style guide:
- 2-space indents
- All indents are spaces, not tabs.
- Wrap lines at 80 characters.
vim djoauth2/... vim djoauth2/tests/...
If your changes touched the models.py file, you must attempt to generate a South migration in case the schema has changed.
It’s important that for backwards-compatibility reasons you use South version 0.7.6 and Django 1.4.3 to generate migration files. After entering the dev-env virtualenv, run the following commands:
pip install Django==1.4.3 pip install South==0.7.6
Then, generate the migrations with the included script:
./generate_migrations.py # Now, test to see that they apply without an error. ./generate_migrations.py --test-migrations
DJOAuth2 is a standalone Django application, which can be hard to test. To obviate a need for installing and re-installing inside of a test project, we provide a script (runtests.py) that sets up a minimal Django environment To use it, enter your shell and run:
# Run all of the tests ./runtests.py # or make tests # Run a group of tests ./runtests.py djoauth2.tests.TestAuthorizationCodeEndpoint # Run an individual test ./runtests.py djoauth2.tests.TestAuthorizationCodeEndpoint.test_get_requests_succeed
While we don’t fetishize 100% coverage, it can be useful to double check that testing actually exercised the code that you added.
To get a coverage report, run make coverage. This will output a brief summary report in the terminal and also generate an interactive HTML version of the report. The interactive version will display the code line-by-line and highlight any code that was not covered by the tests.
# Generate the coverage report make coverage # Fire up a webserver to view the interactive HTML version cd docs/coverage/ python -m SimpleHTTPServer 8080 # Now navigate to localhost:8080 in a browser
Made changes that require documentation (hint: probably)? Rebuild the docs:
And view them in your browser locally:
cd docs/_build/html python -m SimpleHTTPServer 8080 Now navigate to localhost:8080 in a browser
By the way, if you have any questions, concerns, or complaints about the current documentation, please let us know and/or submit a pull request! We’re committed to making the docs as easy to use as possible, so if something is not working we’d love to hear it.
Once your changes are finished (including tests and documentation) it’s time to commit them:
git commit -a -m "Add my new feature."
Submitting a pull request¶
Once your changes are locally committed and tested, it’s time to submit a pull request to get your changes reviewed and merged upstream. Again, Github has a nice overview here.
- Push your changes to your github repository:
git push origin my-feature-branch
- In Github, switch to my-feature-branch
- Click on the large green “compare & pull request” button:
- Write up a nice explanation of your changes and fire it off!