Contributing
Patches are more than welcome! You can find the issue tracker on GitHub and we’d love pull requests.
Setup
To install all the requirements (probably into a virtualenv):
pip install -e .
pip install -e ".[dev]"
This installs:
All the text requirements
All the typing requirements
pre-commit, for checking styles
tox, for running tests against multiple environments
Sphinx and document building requirements
Style
Patches should follow PEP8 and should not introduce any new violations as detected by the ruff tool.
To help stay on top of this, install pre-commit, and then run pre-commit install-hooks. Now you’ll be set up
to auto-format your code according to our style and check for errors for every commit.
Tests
Patches fixing bugs should include regression tests (ideally tests that fail without the rest of the patch). Patches adding new features should test those features thoroughly.
To run the tests, install the requirements (probably into a virtualenv):
pip install -e .
pip install -e ".[tests]"
Then just pytest to run the tests:
pytest
To run the tests with coverage and get a report, use the following command:
pytest --cov=csp --cov-config=.coveragerc
To run the tests like Github Actions does, you’ll need pyenv:
pyenv install 3.9 3.10 3.11 3.12 pypy3.9 pypy3.10
pyenv local 3.9 3.10. 3.11 3.12 pypy3.9 pypy3.10
pip install -e ".[dev]" # installs tox
tox # run sequentially
tox run-parallel # run in parallel, may cause issues on coverage step
tox -e 3.12-4.2.x # run tests on Python 3.12 and Django 4.x
tox --listenvs # list all the environments
Type Checking
New code should have type annotations and pass mypy in strict mode. Use the typing syntax available in the earliest supported Python version 3.9.
To check types:
pip install -e ".[typing]"
mypy .
If you make a lot of changes, it can help to clear the mypy cache:
mypy --no-incremental .
Updating Documentation
To rebuild documentation locally:
pip install -e ".[dev]"
cd docs
make html
open _build/html/index.html # On macOS