A cookiecutter template for data science projects within His Majesty's Government and wider public sector.
govcookiecutter
A cookiecutter template for analytical, Python-, or Python and R-based projects within His Majesty's Government, and wider public sector.
This template helps to set up standardised project structures, and includes security features using pre-commit hooks. This cookiecutter template also acts as an installable template (python projects only).
It also provides an Agile, centralised, and lightweight analytical quality assurance (AQA) process. Pull or merge request templates are used to nudge users to complete this process. This helps meet HM Government best practice on producing quality analysis, as defined in the Aqua Book.
For reasons why we developed govcookiecutter
, read the blog post, and
watch the live demonstration from March 2021 on version 0.5.3.
First, make sure your system meets the requirements. Next, open your terminal, navigate to the directory where you want your new repository to exist. Then run the following command for the latest stable release:
python -m cookiecutter https://github.com/best-practice-and-impact/govcookiecutter.git
or for a specific branch, tag, or commit SHA {SPECIFIC}
, run:
python -m cookiecutter https://github.com/best-practice-and-impact/govcookiecutter.git --checkout {SPECIFIC}
Follow the prompts; if you are asked to re-download govcookiecutter
, input yes
.
Default responses are shown in the squared brackets; to use them, leave your response
blank, and press enter.
Once you've answered all the prompts, your project will be created. Then:
Set up a Python virtual environment — there are many ways to set up a virtual environment, so we'll let you decide what's best for you!
In your terminal, navigate to your new project, and initialise Git
git init
Install the necessary packages using pip
and the pre-commit hooks:
python -m pip install -U pip setuptools
python -m pip install -e .[dev]
pre-commit install
or use the make
command:
make install_dev
Stage all your project files, and make your first commit
git add .
git commit -m "Initial commit"
Once you've completed these steps, consider making some optional changes before kicking off your project development.
Contributors have some additional requirements!
To get started your system should meet the following requirements:
cookiecutter
package installed
[^1]: Only for combined Python and R projects, if selected in the prompts during project creation.
cookiecutter
packageThere are many ways to install the cookiecutter
package. Our recommendation is to
install it at the system or user level, rather than as a Python package with pip
or
conda
. This ensures it is isolated from the rest of your system, and always available.
For macOS, open your terminal, and install cookiecutter
with Homebrew:
brew install cookiecutter
For Debian/Ubuntu, use the following commands:
sudo apt-get install cookiecutter
Otherwise, you can install cookiecutter
with pip
— you may wish to create a virtual
environment first:
python -m pip install --user cookiecutter
Here are some suggested changes to make before your first commit:
cruft
package to integrate future govcookiecutter
releases
pip install cruft
cruft link https://github.com/best-practice-and-impact/govcookiecutter
README.md
reflects what you want to do with your projectdocs/aqa
folder, as you may want to modify some of this
analytical quality assurance documentation (AQA), for example the AQA plan.github/pull_request_template.md
(GitHub), or in
.gitlab/merge_request_templates
folder (GitLab)Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.
If you want to help us build, and improve govcookiecutter
, view our contributing
guidelines.
This template is based off the DrivenData Cookiecutter Data Science
project. Specifically, it uses a similar src
folder structure,
and a modified version of the help
commands in the Makefile
s.