We love contributions! We've compiled this documentation to help you understand our contributing guidelines. If you still have questions, please contact us and we'd be happy to help!
Code of Conduct
CODE_OF_CONDUCT.md before contributing.
To start contributing, open your terminal, and install the required Python packages, and pre-commit hooks using:
pip install -r requirements.txt pre-commit install
The pre-commit hooks are a security feature to ensure, for example, no secrets[^1], large data files, and Jupyter notebook outputs are accidentally committed into the repository. For more information on pre-commit hooks see our documentation.
[^1]: Only secrets of specific patterns are detected by the pre-commit hooks.
We mainly follow the GDS Way in our code conventions.
Git and GitHub
We use Git to version control the source code. Please read the GDS Way for details on
Git best practice. This includes how to write good commit messages, use
git rebase for local branches and
git merge --no-ff for merges, as well as using
git push --force-with-lease instead of
git push -f.
If you want to modify the
.gitignore files, see the template
documentation for further details.
Our source code is stored on GitHub. Pull requests into
main require at least one
For Python code, we follow the GDS Way Python style guide with a line length of 88; the flake8 pre-commit hook should help with this!
Local links can be written as normal, but external links should be referenced at the bottom of the Markdown file for clarity. For example:
Use a [local link to reference the `README.md`](../../README.md) file, but [an external link for GOV.UK][gov-uk]. [gov-uk]: https://www.gov.uk/
We also try to wrap Markdown to a line length of 88 characters, but this is not strictly enforced in all cases, for example with long hyperlinks.
Tests are written using the
pytest framework, with its configuration in the
pyproject.toml file. Note, only tests in the
tests folder are run. To run the
tests, enter the following command in your terminal:
Code coverage of Python scripts is measured using the
package; its configuration can be found in
pyproject.toml. Note coverage
only extends to Python scripts in the
To run code coverage, and view it as an HTML report, enter the following command in your terminal:
coverage run -m pytest coverage html
or use the
The HTML report can be accessed at
We write our documentation in MyST Markdown for use in Sphinx. This is mainly
stored in the
docs folder, unless it's more appropriate to store it elsewhere, like
Please read our guidance on how to write accessible documentation, as well as our guidance on writing Sphinx documentation. This allows you to build the documentation into an accessible, searchable website.