Make Python dev dependencies reproducible with pip-tools hashed lock file

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install pip-tools
+        run: python -m pip install --upgrade pip pip-tools
+
+      - name: Install dev dependencies from lock file
+        run: pip-sync requirements-dev.lock
+
+      - name: Lint with flake8
+        run: flake8 .
+
+      - name: Check formatting with black
+        run: black --check .
+
+      - name: Type-check with mypy
+        run: mypy . || true
+
+      - name: Run tests
+        run: pytest --cov=services tests/

Makefile

@@ -8,4 +8,10 @@ logs:
 	docker-compose logs -f
 
 test:
-	pytest --cov=services tests/
+	pytest --cov=services tests/
+
+lock-dev:
+	pip-compile --generate-hashes requirements-dev.txt --output-file requirements-dev.lock
+
+sync-dev:
+	pip-sync requirements-dev.lock

docs/dev-dependencies.md

@@ -0,0 +1,68 @@
+# Developer Dependencies
+
+This project uses [pip-tools](https://github.com/jazzband/pip-tools) to keep
+dev dependencies reproducible.
+
+| File | Purpose |
+|------|---------|
+| `requirements-dev.txt` | Human-maintained input: list of top-level dev packages |
+| `requirements-dev.lock` | Auto-generated lock file with pinned versions **and SHA-256 hashes** |
+
+---
+
+## Prerequisites
+
+Install pip-tools once into your virtual environment:
+
+```bash
+python -m pip install pip-tools
+```
+
+---
+
+## Compiling the lock file
+
+Re-generate `requirements-dev.lock` from `requirements-dev.txt`:
+
+```bash
+make lock-dev
+# equivalent: pip-compile --generate-hashes requirements-dev.txt --output-file requirements-dev.lock
+```
+
+Commit the updated `requirements-dev.lock` along with any changes to
+`requirements-dev.txt`.
+
+---
+
+## Installing / syncing from the lock file
+
+Install the exact locked versions (removes any packages not in the lock file):
+
+```bash
+make sync-dev
+# equivalent: pip-sync requirements-dev.lock
+```
+
+---
+
+## Updating dependencies (minor/patch)
+
+To pull in the latest compatible minor/patch releases:
+
+```bash
+pip-compile --upgrade --generate-hashes requirements-dev.txt --output-file requirements-dev.lock
+```
+
+Or upgrade a single package (e.g. `pytest`):
+
+```bash
+pip-compile --upgrade-package pytest --generate-hashes requirements-dev.txt --output-file requirements-dev.lock
+```
+
+After compiling, sync your environment:
+
+```bash
+make sync-dev
+```
+
+Then commit both `requirements-dev.txt` (if changed) and `requirements-dev.lock`.