Contributing

We love contributions! We’ve compiled this documentation to help you understand our contributing guidelines. Please also read our CODE_OF_CONDUCT.md.

If you still have questions, please contact us at ASAP@ons.gov.uk and we’d be happy to help!

Getting started

To start contributing, open your terminal and install the package and pre-commit hooks using:

pip install -r requirements.txt
pre-commit install

or use the make command if it is available on your platform (Windows users may have difficulty):

make install_dev

The pre-commit hooks are a security feature to ensure, for example, no secrets, large data files, or Jupyter notebook outputs are accidentally committed into the repository. For more information and common use cases, please refer to a hook’s documentation such as detect-secrets or nbstripout.

Code conventions

We mainly follow the GDS Way in our code conventions. For Python code, we follow the GDS Way Python style guide, and use the flake8 pre-commit hook for linting.

Git and GitHub

We use Git to version control the source code. Please read the Quality assurance of code for analysis and research for details on Git best practice. This includes how to write good commit messages, how to branch appropriately and solve merge conflicts.

The .gitignore used in this repository was created with generic exclusions from gitignore.io. You will need to enter your programming language of choice (i.e. Python) and click “Create”.

Pull requests into main require at least one approved review.

Spotted a bug?

Raise an issue using the bug report template - please check the issues first in case we’re already on it!

Want to see a new feature?

We’d be delighted to consider it! Please raise an issue using the feature request template after checking the issues in case you can add to an ongoing discussion.

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 a README.md file for example, but an external link for 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 hooks, and {{ cookiecutter.repo_name }}/{{ cookiecutter.repo_name.lower().replace(' ', '_').replace('-', '_') }} folders.

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 make command:

make coverage_html

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

Documentation

Documentation is stored in the docs folder unless it’s more appropriate to store it elsewhere, like this contributing guidance. We write our documentation in MyST Markdown for use in Sphinx, to make a searchable wesite. Public sector websites must be accessible by law, and GOV.UK has further information on these requirements.

To create the website locally, run the following command in your terminal at the top-level of this project:

make docs

This should create an HTML version of your documentation accessible from docs/_build/index.html.

Organisational frameworks

Organisational frameworks are stored in the .govcookiecutter/organisational_frameworks folder. [If you would like to add your own organisation’s framework, follow the instructions][docs-govcookiecutter-frameworks] in the README.md file in that folder.