Contributing to Divák¶
So you want to contribute back to Divák.
Thank you
This project is released under the permissive BSD license so you aren’t required to contribute modifications. But you are obviously a person of excellent taste since you found your way here. The first thing that you will want to do is to create a fork of
and clone it to your workstation/laptop/phone/whatever:
git clone git@github.com:your-org/divak-tornado.git
Then you can move forward with your development.
Development Environment¶
This library is primarily developed in Python 3 so start by setting up a new
virtual environment named env
in the root directory. I’m not usually so
opionated as to tell you what to name things but env
is wired through the
.gitignore file and that’s what I will be using in examples. If you put the
environment somewhere else, then that works too but you will have to do a
minor amount of mental gymnastics to follow along:
python3.6 -mvenv --copies env
Next you want to install the development tools using the pip-formatted requirements file requires/development.txt. This will ensure that you are using the same versions of development tools that tests will be run with:
./env/bin/pip -r requires/development.txt
Before you start writing code, do yourself a big favor and make sure that the tests pass on your local machine. They should pass but you are better off safe than sorry:
./env/bin/python setup.py nosetests
If they pass, then it’s time to start writing code; otherwise, reach out and
file a github issue with the output of pip freeze
, the test output, and
any logs that you have handy.
Development Tasks¶
Most of the tasks are wired up to be run using setup.py so activate the environment and run ./setup.py … to run a utility. Of course you are more than welcome to use nosetests, sphinx-build, and other utilities directly.
- setup.py nosetests will run the test suite. Add –with-coverage to generate coverage reports to build/coverage as well.
- setup.py flake8 will run the PEP8 checker
- setup.py build_sphinx will build the documentation suite into build/sphinx/html
- setup.py bdist_wheel will build a wheel distribution into the dist directory
Submitting a PR¶
Once you have made your changes, its time to submit a pull request against the upstream repository. Just go through the following checklist before you create the PR since the integrated CI will fail unless you do:
- ensure that all of the tests are passing
- ensure that any new code or branches are covered by tests – I aim for 100% test coverage on lines and branches
- describe your changes in the Next Release section of docs/changelog.rst
- push your changes to your fork and issue the PR
Once again, thank you very much for taking the time to contribute back.