CONTRIBUTING.md

Contributing

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

Please read CODE_OF_CONDUCT.md before contributing.

Getting started

To start contributing, first make sure your system meets these requirements:

1. Python 3.6.1+ installed
2. poetry installed; see their documentation for instructions

Then install the required Python packages, and Git pre-commit hooks using:

poetry run make dependencies

It is better to use the above make command, rather than poetry install and poetry run pre-commit install. This make command will ensures your pre-commit hooks are up-to-date with any changes made.

The pre-commit hooks are a security feature to ensure, for example, no secrets¹, and large data files, are accidentally committed into the repository. For more information on pre-commit hooks see our documentation.

Code conventions

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 approved review.

Python

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!

Markdown

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.

Testing

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:

pytest

Code coverage

Code 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 govuk_tech_docs_sphinx_theme folder.

To run code coverage, and view it as an HTML report, enter the following command in your terminal:

poetry run make coverage_html

The HTML report can be accessed at htmlcov/index.html.

Documentation

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.

Footnotes

1. Only secrets of specific patterns are detected by the pre-commit hooks. ↩