All contributions are welcome! Besides code contributions, this includes things like documentation improvements, bug reports, and feature requests.
You should first check if there is a GitHub issue already open or related to what you would like to contribute. If there is, please comment on that issue to let others know you are working on it. If there is not, please open a new issue to discuss your contribution.
Not all contributions need to start with an issue, such as typo fixes in documentation or version bumps to Python or Django that require no internal code changes, but generally, it is a good idea to open an issue first.
We adhere to Django's Code of Conduct in all interactions and expect all contributors to do the same. Please read the Code of Conduct before contributing.
- uv - Modern Python toolchain that handles:
- Python version management and installation
- Virtual environment creation and management
- Fast, reliable dependency resolution and installation
- Reproducible builds via lockfile
- direnv (Optional) - Automatic environment variable loading
- just (Optional) - Command runner for development tasks
The repository includes a Justfile
that provides all common development tasks with a consistent interface. Running just
without arguments shows all available commands and their descriptions.
$ just
$ # just --list --list-submodules
Available recipes:
bootstrap
coverage *ARGS
lint
lock *ARGS
manage *COMMAND
test *ARGS
testall *ARGS
types *ARGS
copier:
copy TEMPLATE_PATH DESTINATION_PATH="." # Create a copier answers file
recopy ANSWERS_FILE *ARGS # Recopy the project from the original template
recopy-all *ARGS # Loop through all answers files and recopy the project using copier
update ANSWERS_FILE *ARGS # Update the project using a copier answers file
update-all *ARGS # Loop through all answers files and update the project using copier
docs:
build LOCATION="docs/_build/html" # Build documentation using Sphinx
serve PORT="8000" # Serve documentation locally
project:
bump *ARGS
release *ARGS
All commands below will contain the full command as well as its just
counterpart.
The following instructions will use uv
and assume a Unix-like operating system (Linux or macOS).
Windows users will need to adjust commands accordingly, though the core workflow remains the same.
Alternatively, any Python package manager that supports installing from pyproject.toml
(PEP 621) can be used. If not using uv
, ensure you have Python installed from python.org or another source such as pyenv
.
-
Fork the repository and clone it locally.
-
Use
uv
to bootstrap your development environment.uv python install uv sync --locked # just bootstrap
This will install the correct Python version, create and configure a virtual environment, and install all dependencies.
The project uses pytest
for testing and nox
to run the tests in multiple environments.
To run the test suite against the default versions of Python (lower bound of supported versions) and Django (lower bound of LTS versions):
uv run nox --session test
# just test
To run the test suite against the entire matrix of supported versions of Python and Django:
uv run nox --session tests
# just testall
Both can be passed additional arguments that will be provided to pytest
.
uv run nox --session test -- -v --last-failed
uv run nox --session tests -- --failed-first --maxfail=1
# just test -v --last-failed
# just testall --failed-first --maxfail=1
The project uses coverage.py
to measure code coverage and aims to maintain 100% coverage across the codebase.
To run the test suite and measure code coverage:
uv run nox --session coverage
# just coverage
All pull requests must include tests to maintain 100% coverage. Coverage configuration can be found in the [tools.coverage.*]
sections of pyproject.toml
.
This project enforces code quality standards using pre-commit
.
To run all formatters and linters:
uv run nox --session lint
# just lint
The following checks are run:
- ruff - Fast Python linter and formatter
- Code formatting for Python files in documentation (blacken-docs)
- Django compatibility checks (django-upgrade)
- TOML and YAML validation
- Basic file hygiene (trailing whitespace, file endings)
To enable pre-commit hooks after cloning:
uv run --with pre-commit pre-commit install
Configuration for these tools can be found in:
.pre-commit-config.yaml
- Pre-commit hook configurationpyproject.toml
- Ruff and other tool settings
This project uses GitHub Actions for CI/CD. The workflows can be found in .github/workflows/
.
test.yml
- Runs on pushes to themain
branch and on all PRs- Tests across Python/Django version matrix
- Static type checking
- Coverage reporting
release.yml
- Runs on GitHub release creation- Runs the
test.yml
workflow - Builds package
- Publishes to PyPI
- Runs the
PRs must pass all CI checks before being merged.