Dependency Pinning Manifest

Ratified posture for how Apothem declares, pins, and locks dependencies. Audience: contributors and downstream consumers who need to understand the reproducibility model.

PostureCopy Anchor Link

Apothem is a Python CLI with a small runtime dependency set plus a larger development, audit, release, and documentation toolchain. Runtime dependencies use conservative lower bounds in pyproject.toml; the website commits site/package-lock.json; GitHub Actions are pinned by immutable SHA with version comments and are bumped by Dependabot.

Release ratificationCopy Anchor Link

LockingCopy Anchor Link

Contributors' own Python lock files are generated on demand and are not committed: Apothem's runtime closure is small and the CLI supports multiple Python minor versions. CI is the exception. It installs the hash-locked files in scripts/ci/: four dependency locks (requirements-ci-dev.txt, -runtime.txt, -test.txt and -prereqs.txt) and one lock per tool the workflows run (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt and -pre-commit.txt). python scripts/dev/refresh_ci_locks.py compiles all nine as of a lock date, less a 7-day cooldown that matches Dependabot's, so CI tests the releases that were at least a week old on the lock date and refreshing the files moves them forward. Each file records the lock date, the cooldown and the resulting cutoff, and --check reproduces the cutoff. An urgent security fix that is younger than the cooldown needs a refresh run with --cooldown-days 0, or a cooldown exception for its package in scripts/dev/ci_lock_table.py, which lifts the cooldown for that package alone. The weekly pip-audit.yml run audits the newest versions pyproject.toml allows as well as the nine locks, asking the OSV service for advisories. Contributors keep installing with pip install -e ".[dev]".

# Astral uv:
uv pip install -e ".[dev,security,release]"
uv pip freeze > requirements.dev.lock

# pip-tools:
pip-compile --extra=dev --extra=security --extra=release -o requirements.dev.lock pyproject.toml

# Plain pip:
pip install -e ".[dev,security,release]"
pip freeze > requirements.dev.lock

The website is different: site/package-lock.json is committed and CI uses npm ci, so the rendered documentation site has a reproducible Node closure.

RationaleCopy Anchor Link

• Why range pins for Python? The CLI supports a broad Python matrix, so pyproject.toml keeps conservative floors. CI installs hash-locked closures of those ranges, which the maintainer refreshes with scripts/dev/refresh_ci_locks.py (weekly is the intended cadence), and the weekly pip-audit.yml run resolves the newest allowed versions to reveal problems with current tooling.
• Why a committed Node lock? The website is a deployed static artifact; the lockfile gives deterministic npm ci builds for that public surface.
• Why SHA-pinned Actions? Tags are mutable; SHAs are immutable. Dependabot proposes the SHA bumps and rewrites each version comment, while the release gate records any intentional hold.
• What the update bot does not touch. Dependabot version updates (.github/dependabot.yml) cover the GitHub Actions pins, the website lockfile, the vsce packager lockfile (tools/vsce), the harness-CLI lockfile the channel smoke installs (tools/channel-smoke), the hash-locked pip that CI installs (scripts/ci/requirements-ci-pip.txt) and the pre-commit hooks. The other nine files in scripts/ci are closures regenerated whole with scripts/dev/refresh_ci_locks.py, none of them pins pip, and Dependabot's version updates for that folder are limited to pip. The runtime floors in pyproject.toml, the hash-locked release requirements, the vendored closure in src/apothem/_vendor/vendor.txt and the pre-commit hooks pinned in lockstep with pyproject.toml move by hand, because a single-pin bump would break the files they agree with. The ruff and mypy hooks are two of them: tests/scripts/test_ci_tool_locks.py fails until the exact ruff pin in pyproject.toml, the hook rev, the ruff lock and the dev lock carry one version, and until the exact mypy pin, the mypy hook rev and the libraries that hook lists match the dev lock, so a Dependabot security pull request for either tool is adapted by hand. The website's @types/node major follows its Node floor (engines and .nvmrc, Node 22), so Dependabot proposes only its minor and patch updates; raise that major together with the floor. Version updates leave npm overrides blocks alone. Dependabot security updates still cover every manifest, so a security pull request can propose one of these pins, or move an override; adapt it by hand or close it.
• Merging a Dependabot pull request. The repository's squash default takes the PR title. Some Dependabot titles, mostly grouped ones that name a directory, run past the 72-character squash subject; the PR Title check names them, and a retitle fixes them. A pull request that changes a tool lockfile runs no ci.yml job, so the npm audit workflow audits and installs it, packages the VS Code extension for the vsce lockfile and runs the vsce release tests, and the channel smoke workflow runs for the channel-smoke lockfile. The Markdown Lint workflow runs the markdownlint hook on a pre-commit hooks pull request; the other hooks are not exercised in CI, so run pre-commit run --all-files on its branch before merging it.