Contribution guidelines

Medium-term plans and milestones

Add draft work items to the project board, and discuss!
- All members of the Burman group should have access.
- Feel free to request access if you don't have it.

Open draft pull requests (PRs) early, especially if you want early feedback on a feature.
- Try to avoid "grand unveilling" of large pieces of work. In general multiple more focused smaller PRs are better than one large monolithic PR.
- Try to keep focused on "one feature" or "one issue". Aim to minimise unrelated code changes per PR.
Convert to "Ready for review" when there are no changes expected from the requester side and add, minimally, one reviewer.
New features should be covered by new test(s), unless it's obviously already tested.
All tests should pass and all linting should pass. Test coverage should, at least, stay the same.
If a reviewer has no comments or questions, and all required checks are passing in the CI, then the approving reviewer is encouraged to merge the PR themselves to keep things tidy.
Merge via squash merge (so we have one commit per PR).

We aim for PEP8-compliant Python code with one exception:

Capital letters for matrices (following conventional math notation).
- The linter will flag up the use of i.e. A as a variable name. Silence this with # noqa: N803.
Aim to document all public-facing application programming interface (API) code with Google-style docstrings.
Aim for PEP484 type annotations throughout. Check with mypy or pre-commit.
- No need to put type hints in docstrings.

We use pre-commit for linting. It should have been installed as a development dependency (when you ran python -m pip install -e ".[dev]").

You should simply be able to run:

pre-commit install # first time only

which downloads and installs pre-commit hooks and linters. To run, from the root of the repository, do:

pre-commit run