Local Development
This page documents day-to-day local workflows for maintainers. Repository-level and external service setup remains in Repository and Tooling Setup.
Prerequisites
A Python version within the current support window (last three Python versions)
Poetry package manager
Install dependencies
poetry install --no-interaction --with docs
Run tests
Run the test suite and dependency compatibility matrix with nox:
poetry run nox
Run the full suite without matrix testing:
poetry run python src/manage.py test
Run a specific test module:
poetry run python src/manage.py test tests.test_serializer
Run a single test case:
poetry run python src/manage.py test tests.test_serializer.YourTestCase
Run test coverage
Coverage is configured in pyproject.toml and enforced with a
fail_under threshold of 90%.
Run coverage from the repository root:
export PYTHONPATH=src
poetry run coverage run --rcfile=pyproject.toml src/manage.py test tests
poetry run coverage report --rcfile=pyproject.toml -m
If coverage fails, review the Missing column and add tests for the
reported lines or branches before opening a PR.
Build documentation
poetry run sphinx-build -W -T -v docs/ site/
What these options do:
-W: Treat warnings as errors (to catch broken references)-T: Print tracebacks-v: Verbose output (-v -v even more verbose)
Deliberately not included is --keep-going, because it may swallow errors.
Common maintenance commands
Show dependency graph:
poetry show --treeUpdate lock file after dependency changes:
poetry lockBump package version:
poetry version patch(orminor/major)
Daily checklist
Pull latest
main.Run tests.
Run coverage and confirm it stays at or above 90%.
Run docs build if public behavior or docs changed.
Keep changelog updates in Change Log for user-visible changes.