Contributing to this project is easy, and reporting an issue or adding to the documentation also improves things for every user. You don’t need to be a developer to contribute.
Please use the GitHub issue tracker, and describe your problem so that it can be easily reproduced. Providing relevant version information on the project itself and your environment helps with that.
The easiest way to provide examples or related documentation that helps other users is the GitHub wiki.
If you are comfortable with the Sphinx documentation tool, you can also prepare a pull request with changes to the core documentation. GitHub’s built-in text editor makes this especially easy, when you choose the “Create a new branch for this commit and start a pull request” option on saving. Small fixes for typos and the like are a matter of minutes when using that tool.
Here’s a quick guide to improve the code:
- Fork the repo, and clone the fork to your machine.
- Add your improvements, the technical details are further below.
- Run the tests and make sure they’re passing (
- Check for violations of code conventions (
- Make sure the documentation builds without errors
invoke build --docs).
- Push to your fork and submit a pull request.
Please be patient while waiting for a review. Life & work tend to interfere.
Details on contributing code¶
This project is written in Python, and the documentation is generated using Sphinx. setuptools and Invoke are used to build and manage the project. Tests are written and executed using pytest and tox.
Set up a working development environment¶
To set up a working directory from your own fork, follow these
but replace the repository
https URLs with SSH ones that point to
For that to work on Debian type systems, you need the
python-virtualenv packages installed. Other
distributions are similar.
Add your changes to a feature branch¶
For any cohesive set of changes, create a new branch based on the
master, with a name reflecting the essence of your
git branch "name-for-my-fixes" origin/master git checkout "name-for-my-fixes" … make changes… invoke ci # check output for broken tests, or PEP8 violations and the like … commit changes… git push origin "name-for-my-fixes"
Please don’t create large lumps of unrelated changes in a single pull request. Also take extra care to avoid spurious changes, like mass whitespace diffs. All Python sources use spaces to indent, not TABs.
Make sure your changes work¶
Some things that will increase the chance that your pull request is accepted:
- Follow style conventions you see used in the source already (and read PEP8).
- Include tests that fail without your code, and pass with it. Only minor refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, please also add a test for it!
- Update any documentation or examples impacted by your change.
- Styling conventions and code quality are checked with
invoke check, tests are run using
invoke test, and the docs can be built locally using
invoke build --docs.
Following these hints also expedites the whole procedure, since it avoids unnecessary feedback cycles.