Skip to content

Latest commit

 

History

History
151 lines (113 loc) · 6.44 KB

CONTRIBUTING.md

File metadata and controls

151 lines (113 loc) · 6.44 KB
Raw

Contributing

#TODO: update stance on internal/external contribution

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, open your terminal, and install the required Python packages, and pre-commit hooks using:

pip install -r requirements.txt
pip install -r requirements-dev.txt
pre-commit install

or the make command:

make requirements

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

Code conventions

Code written for this project should follow PEP 8 coding conventions, project naming conventions and the guidance on quality assurance of code for analysis and research (also known as the Duck Book).

Git and GitHub

We use Git to version control the source code and out source code is stored on GitHub.

We follow the GitHub flow workflow. This means that we create feature branches of the main branch and merge them back to main once they meet the definition of done. We give our branches short but informative names, in lowercase and separated with hypens. Where applicable, we start branch names with the respective Jira ticket number. For example, 318-forward-matched-pairs.

We commit regularly, with distinct chunks of work where possible. We write short but informative commit messages, starting with a capitalised present-tense verb, for example Add, Fix. When pair-programming, we add co-authors to the commit. We add longer commit messages for larger or more complex commits, for example (squash) merge commits.

We open a pull request to main once we have working code that meets a user need, for example meets the definition of done on the Jira ticket. Pull requests must be reviewed by at least one member of the team before merging. Reviews should follow the pull request template. If we want review on code that does not yet meet the definition of done, we open a draft pull request. Once a branch has been reviewed, it can be merged. We prefer to use squash merges, in order to simplify the main branch commit history. After merging the feature branch should be deleted.

Functions

We prefer writing functions over classes to make it easier for beginners to understand the code. Type hints should be used when writing functions. We prefer functions to return pandas.DataFrame rather than pandas.Series, for example when deriving new (temporary) variables.

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 file, 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

Our testing approach is:

  • use .csv files containing simple minimal input and output data for a function to be tested
  • individual test cases should be separated into different .csv files and grouped into folders
  • the name of the test data .csv files should reflect the test case and the folder name should be the same as the module/function

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 src folder.

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

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.

Footnotes

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