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:

  1. ensure that all of the tests are passing
  2. ensure that any new code or branches are covered by tests – I aim for 100% test coverage on lines and branches
  3. describe your changes in the Next Release section of docs/changelog.rst
  4. push your changes to your fork and issue the PR

Once again, thank you very much for taking the time to contribute back.