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!
Please read CODE_OF_CONDUCT.md before contributing.
To start contributing, first ensure your system meets the requirements. Next, install the required Python packages, and pre-commit hooks using:
make requirementsIt is better to use the above make command, rather than
pip install -r requirements.txt and pre-commit install, as the command will ensure
your pre-commit hooks are up-to-date with any changes made.
The pre-commit hooks are a security feature to ensure no secrets1, large data files, and Jupyter notebook outputs are accidentally committed into the repository. For more information about the pre-commit hooks used in this repository, see the documentation.
We mainly follow The GDS Way in our code conventions.
We use Git to version control the source code; please read The GDS Way
for further details, including information about writing good commit messages, using
git rebase for local branches, and git merge --no-ff for merges, as well as the
entry on 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 approved review.
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 executed. To run the
tests, execute the following command in your terminal:
pytestCode coverage of Python scripts is measured using the coverage Python
package; its configuration can be found in pyproject.toml. Note coverage only extends
to Python scripts in the src folder.
To run code coverage, and view it as an HTML report, execute the following commands in your terminal:
coverage run -m pytest
coverage htmlThe HTML report can be accessed at htmlcov/index.html.
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
this file.
Please read our guidance on how to write Sphinx documentation, and build it into a searchable website.
[1]: Only secrets of specific patterns are detected by the pre-commit hooks.