Coordinate First

Before you create a pull request, please create a new issue first or check in on gitter to coordinate.

It might be that we are already working on the same or similar feature, but we haven’t made our work visible yet.

Create a Development Environment

We usually develop in a virtual environment. To create one, change to the root directory of the repository and invoke:

python -m venv venv

You need to activate it. On nix (Linux, Mac, *etc.):

source venv/bin/activate

and on Windows:


Install Development Dependencies

Once you activated the virtual environment, you can install the development dependencies using pip:

pip3 install --editable .[dev]

The –editable option is necessary so that all the changes made to the repository are automatically reflected in the virtual environment (see also this StackOverflow question).

Pre-commit Checks

We provide a battery of pre-commit checks to make the code uniform and consistent across the code base.

We use black to format the code and use the default maximum line length of 88 characters.

To run all pre-commit checks, run from the root directory:

pre-commit run --all-files

The pre-commit hooks also run as part of our continuous integration pipeline.


The pre-commit command will run smoke tests, but you should run the full set of tests with pytest too; use a command like this:

env PYTHONHASHSEED=0 python -m pytest -n auto --dist worksteal

There are many tests, but they parallelize; having more cores will help a lot. Note that the super fest tests run first; don’t assume pytest is hanging later on!

Write Commit Message

We follow Chris Beams’ guidelines on commit messages:

  1. Separate subject from body with a blank line

  2. Limit the subject line to 50 characters

  3. Capitalize the subject line

  4. Do not end the subject line with a period

  5. Use the imperative mood in the subject line

  6. Wrap the body at 72 characters

  7. Use the body to explain what and why vs. how

Contributor List

In order of initial commit. Many thanks!