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:
- Python 3.6.1+ installed
- R 4.0.4+ installed (optional)1
- The
cookiecutter
package installed
There 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:
- consider using the
cruft
package to integrate futuregovcookiecutter
releasespip install cruft cruft link https://github.com/best-practice-and-impact/govcookiecutter
- make sure the
README.md
reflects what you want to do with your project - have a look inside the
docs/aqa
folder, as you may want to modify some of this analytical quality assurance documentation (AQA), for example the AQA plan - (if present) confirm that the pull or merge request template checklists meet your
requirements
- These can be found at
.github/pull_request_template.md
(GitHub), or in.gitlab/merge_request_templates
folder (GitLab)
- These can be found at
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.
Footnotes
-
Only for combined Python and R projects, if selected in the prompts during project creation. ↩