upgrade

Upgrade & Maintenance Guide

Purpose. How to refresh this template's pinned artifacts (deps, actions, scanner images, the ODW and J-Space submodules) and how a project derived from this template pulls in upstream template fixes. This is a process doc, not one of the 10 core documents.

One rule above all: everything is pinned (Python deps by hash, GitHub Actions by commit SHA, scanner containers by image digest, OpenGrep by SHA-256, ODW and J-Space by submodule commit). An upgrade is a deliberate, reviewed pin rotation — never a floating reference.

---

1. Python dependencies

Lockfiles (requirements.txt, requirements-dev.txt, requirements-notebooks.txt) are compiled from the .in sources with hashes. Never edit a .txt directly; bump the .in and re-compile.

# Edit the source pins (e.g. bump a floor, add a dep) in requirements*.in,
# then regenerate every lockfile WITH hashes from a clean Python 3.12 env:
pip-compile --generate-hashes --allow-unsafe --resolver=backtracking \
  requirements.in -o requirements.txt
pip-compile --generate-hashes --allow-unsafe --resolver=backtracking \
  requirements-dev.in -o requirements-dev.txt
pip-compile --generate-hashes --allow-unsafe --resolver=backtracking \
  requirements-notebooks.in -o requirements-notebooks.txt

The [tool.pip-tools] block in pyproject.toml already sets those flags, so a bare pip-compile requirements.in honors them. Track CVE floors with comments in the .in files (e.g. # CVE-2026-XXXX fixed in >=X.Y.Z).

Verify before committing:

python -m pip install --require-hashes -r requirements-dev.txt && python -m pip check
./scripts/security/supply-chain-audit.sh   # pip-audit + OSV-Scanner over BOTH lockfiles

Dependabot does NOT do this. .github/dependabot.yml excludes the pip ecosystem on purpose — Dependabot mutates the compiled .txt directly and fights --require-hashes. Python bumps are always the manual .in → pip-compile flow above.