Tooling, automation and developer experience

Goals and principles

• It should be easy to run the same thing that CI is running. Conversely, CI runs what you're running locally.
• Standard tooling (e.g. ShellCheck) should be available opportunistically: even if a project has no shell scripts yet, ShellCheck should kick in automatically if it acquires one.
• We're using Make as a command-runner, not for any real build logic.
  • Make's main pro is that it's universal, everyone knows "make test", etc. and already has it installed.
  • We do use make as a build tool for client localization targets, but that's not necessary.
• We should use tool-specific configuration (e.g. Black, pytest) rather than committing complex command invocations to Make targets.
  • Makes it easier for new developers who already have experience using the tool to also use the tool here.
  • Helps with other tooling, e.g. IDEs that know how to use the tool in the standard way (e.g. PyCharm can run black to autoformat every time you save a file), but won't know about our wrapper that contains our configuration arguments.

CI overview

Across projects/repositories, we use CI to accomplish the following tasks in the following ways (including the following exceptions/gaps):

Repository	securedrop	securedrop-client	...
CI image
Python version
Runs ShellCheck
...on any and all shell files present, or passes if none
Runs mypy
...in strict mode, including Qt
Runs Black
Runs isort
Runs flake8
Runs safety
Extracts source strings for localization
...if babel.cfg is present, otherwise passes
Caches CI jobs
CI jobs are grouped in workflows
CI jobs are parameterized in matrices

Tooling overview

Across projects/repositories, we use Makefiles and shell scripts to accomplish the following tasks in the following ways (including the following exceptions/gaps):

Repository	securedrop	securedrop-client	...
Create a Python venv	make venv	make venv
Set up Git hooks	make add-hooks	make hooks
Run in a development environment	make dev	./run.sh
Lint (etc.)
Run tests	make test	make test