Manifest zur Abhängigkeitsfixierung

Ratifizierte Haltung dazu, wie Apothem Abhängigkeiten deklariert, fixiert und sperrt. Zielgruppe: Mitwirkende und nachgelagerte Konsumenten, die das Reproduzierbarkeitsmodell verstehen müssen.

HaltungCopy Anchor Link

Apothem ist eine Python-CLI mit einem kleinen Satz an Laufzeitabhängigkeiten plus einer umfangreicheren Werkzeugkette für Entwicklung, Audit, Release und Dokumentation. Laufzeitabhängigkeiten verwenden konservative Untergrenzen in pyproject.toml; die Website committet site/package-lock.json; GitHub Actions werden per unveränderlichem SHA mit Versionskommentaren fixiert und von Dependabot aktualisiert.

Release-RatifizierungCopy Anchor Link

SperrungCopy Anchor Link

Die eigenen Python-Lock-Dateien der Mitwirkenden werden bei Bedarf erzeugt und nicht committet: Apothems Laufzeithülle ist klein, und die CLI unterstützt mehrere Python-Nebenversionen. CI ist die Ausnahme und installiert die hash-gesperrten Dateien in scripts/ci/: vier Abhängigkeits-Locks (requirements-ci-dev.txt, -runtime.txt, -test.txt und -prereqs.txt) und einen Lock je Werkzeug, das die Workflows ausführen (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt und -pre-commit.txt). python scripts/dev/refresh_ci_locks.py kompiliert alle neun zum Stand eines Lock-Datums abzüglich einer Wartezeit von 7 Tagen, die der von Dependabot entspricht. CI testet also die Releases, die am Lock-Datum mindestens eine Woche alt waren, und eine Aktualisierung der Dateien rückt auf neuere Releases vor. Jede Datei hält das Lock-Datum, die Wartezeit und den daraus folgenden Stichtag fest, und --check reproduziert den Stichtag. Ein dringender Sicherheitsfix, der jünger als die Wartezeit ist, braucht einen Aktualisierungslauf mit --cooldown-days 0 oder eine Wartezeit-Ausnahme für sein Paket in scripts/dev/ci_lock_table.py, die die Wartezeit nur für dieses Paket aufhebt. Der wöchentliche Lauf von pip-audit.yml auditiert die neuesten Versionen, die pyproject.toml zulässt, und dazu die neun Locks; die Sicherheitsmeldungen fragt er beim OSV-Dienst ab. Mitwirkende installieren weiterhin mit 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

Die Website ist anders: site/package-lock.json wird committet und CI verwendet npm ci, sodass die gerenderte Dokumentationsseite eine reproduzierbare Node-Hülle hat.

BegründungCopy Anchor Link

• Warum Bereichsfixierungen für Python? Die CLI unterstützt eine breite Python-Matrix, daher hält pyproject.toml konservative Untergrenzen. CI installiert hash-gesperrte Hüllen dieser Bereiche, die der Maintainer mit scripts/dev/refresh_ci_locks.py aktualisiert (vorgesehen ist ein wöchentlicher Rhythmus), und der wöchentliche Lauf von pip-audit.yml löst die neuesten zulässigen Versionen auf, um Probleme mit aktuellen Werkzeugen aufzudecken.
• Warum ein committeter Node-Lock? Die Website ist ein bereitgestelltes statisches Artefakt; die Lock-Datei liefert deterministische npm ci-Builds für diese öffentliche Oberfläche.
• Warum SHA-fixierte Actions? Tags sind veränderlich; SHAs sind unveränderlich. Dependabot schlägt die SHA-Aktualisierungen vor und schreibt jeden Versionskommentar neu, während das Release-Gate jede absichtliche Zurückstellung festhält.
• Was der Update-Bot nicht anfasst. Die Dependabot-Versionsupdates (.github/dependabot.yml) decken die GitHub-Actions-Pins, die Lock-Datei der Website, die Lock-Datei des vsce-Packagers (tools/vsce), die Lock-Datei der Harness-CLIs, die der Channel-Smoke installiert (tools/channel-smoke), das hash-gesperrte pip, das CI installiert (scripts/ci/requirements-ci-pip.txt), und die Pre-Commit-Hooks ab. Die anderen neun Dateien in scripts/ci sind Hüllen, die scripts/dev/refresh_ci_locks.py als Ganzes neu erzeugt; keine davon fixiert pip, und die Dependabot-Versionsupdates für diesen Ordner sind auf pip beschränkt. Die Laufzeit-Untergrenzen in pyproject.toml, die hash-gesperrten Release-Anforderungen, die vendorte Hülle in src/apothem/_vendor/vendor.txt und die Pre-Commit-Hooks, die im Gleichschritt mit pyproject.toml fixiert sind, werden von Hand angehoben, weil die Anhebung einer einzelnen Fixierung die Dateien brechen würde, mit denen sie übereinstimmen müssen. Die ruff- und mypy-Hooks sind zwei davon: tests/scripts/test_ci_tool_locks.py schlägt fehl, bis die exakte ruff-Fixierung in pyproject.toml, die rev des Hooks, der ruff-Lock und der dev-Lock dieselbe Version tragen und bis die exakte mypy-Fixierung, die rev des mypy-Hooks und die Bibliotheken, die dieser Hook auflistet, zum dev-Lock passen. Ein Dependabot-Sicherheits-Pull-Request für eines der beiden Werkzeuge wird daher von Hand angepasst. Die Major-Version von @types/node der Website folgt ihrer Node-Untergrenze (engines und .nvmrc, Node 22), daher schlägt Dependabot nur deren Minor- und Patch-Aktualisierungen vor; heben Sie diese Major-Version zusammen mit der Untergrenze an. Versionsupdates lassen npm-overrides-Blöcke unberührt. Die Dependabot-Sicherheitsupdates decken weiterhin jedes Manifest ab, sodass ein Sicherheits-Pull-Request eine dieser Fixierungen vorschlagen oder einen Override verschieben kann; passen Sie ihn von Hand an oder schließen Sie ihn.
• Einen Dependabot-Pull-Request mergen. Die Squash-Voreinstellung des Repositorys übernimmt den PR-Titel. Manche Dependabot-Titel, meist gruppierte, die ein Verzeichnis nennen, überschreiten die 72 Zeichen des Squash-Betreffs; die PR-Title-Prüfung nennt sie, und eine Umbenennung behebt sie. Ein Pull-Request, der eine Werkzeug-Lock-Datei ändert, führt keinen ci.yml-Job aus; daher auditiert und installiert sie der npm-Audit-Workflow, paketiert für die vsce-Lock-Datei die VS-Code-Erweiterung und führt die vsce-Release-Tests aus, und für die channel-smoke-Lock-Datei läuft der Channel-Smoke-Workflow. Der Markdown-Lint-Workflow führt bei einem Pull-Request für die Pre-Commit-Hooks den markdownlint-Hook aus; die übrigen Hooks werden in CI nicht ausgeübt, führen Sie daher vor dem Mergen pre-commit run --all-files auf seinem Branch aus.