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.