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, install the required Python packages, and pre-commit hooks using:
pip install -r requirements.txt
pre-commit install
or the make
command:
make requirements
The pre-commit hooks are a security feature to ensure, for example, no secrets1, and large data files are accidentally committed into the repository. For more information on pre-commit hooks see our documentation.
We mainly follow the GDS Way in our code conventions.
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][duck-book-version-control]. This includes how to write good commit messages, how to branch correctly and solving merge conflicts.
If you want to modify the .gitignore
files, see the template
documentation for further details.
Our source code is stored on GitHub at
https://github.com/best-practice-and-impact/govcookiecutter. 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!
To keep the file uniform, all links should be referenced at the bottom of the markdown file. This also helps to keep the markdown file organised.
We also try to wrap Markdown to a line length of 88 characters. 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 the tests
folder in the root direcrtory of this project are to run. To run the tests, enter
the following command in your terminal:
pytest tests
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 }}/src
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
.
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 accessible documentation, as well as our guidance on writing Sphinx documentation. This allows you to build the documentation into an accessible, searchable website.
Organisational frameworks are stored in the
.govcookiecutter/organisational_frameworks
folder. If you would like to add your own
organisation's framework, follow the instructions in
the README.md
file in that folder.