Contributor Guide
Thank you for your interest in improving this project. This project is open-source under the Apache license and welcomes contributions in the form of bug reports, feature requests, and pull requests.
Here is a list of important resources for contributors:
How to report a bug
Report bugs on the Issue Tracker.
When filing an issue, make sure to answer these questions:
Which operating system and Python version are you using?
Which version of this project are you using?
What did you do?
What did you expect to see?
What did you see instead?
The best way to get your bug fixed is to provide a test case, and/or steps to reproduce the issue.
How to request a feature
Request features on the Issue Tracker.
How to set up your development environment
Note
For convenience, many of the below processes are abstracted away
and encapsulated in single make
targets.
Tip
Invoking make
without any arguments will display
auto-generated documentation on available commands.
Make sure you have Python 3.7+ and Poetry installed and configured.
Install the package with development requirements:
$ make provision-environment
Tip
Invoking the above without poetry
installed will emit a
helpful error message letting you know how you can install poetry.
How to test the project
We use tox for our test automation framework and pytest for our testing framework.
Run the full test suite:
$ make test
Run mutation tests to validate test suite robustness (Optional):
$ make test-mutations
Note
Test time scales with the complexity of the codebase. Results are cached
in .mutmut-cache
, so once you get past the initial cold start problem,
subsequent mutation test runs will be much faster; new mutations will only
be applied to modified code paths.
Lint the code:
$ make lint
Danger
CI will fail if either testing or code quality fail, so it is recommended to automatically run the above locally prior to every commit that is pushed.
You can also run a specific Python tox
testenv.
For example, invoke the Python3.7 unit test suite like this:
$ make test-py37
Unit tests are located in the tests
directory,
and are written using the pytest testing framework.
Build the documentation:
$ make docs-clean docs-html
Note
For faster feedback loops, this will attempt to automatically open the newly built documentation static HTML in your browser.
How to submit changes
Open a pull request to submit changes to this project.
Your pull request needs to meet the following guidelines for acceptance:
The
tox
test suite must pass without errors and warnings.Include unit tests. This project maintains 100% code coverage.
If your changes add functionality, update the documentation accordingly.
Feel free to submit early, though we can always iterate on this.
To run linting and code formatting checks before commiting your change, you can install pre-commit as a Git hook by running the following command:
$ make install-pre-commit-hooks
Warning
This will prevent commits if any single pre-commit hook fails (unless it is allowed to fail) or a file is modified by an auto-formatting job; in the latter case, you may simply repeat the commit and it should pass.
It is recommended to open an issue before starting work on anything. This will allow a chance to talk it over with the owners and validate your approach.