Manifeste d'épinglage des dépendances

Posture ratifiée sur la manière dont Apothem déclare, épingle et verrouille ses dépendances. Public : contributeurs et consommateurs en aval qui doivent comprendre le modèle de reproductibilité.

PostureCopy Anchor Link

Apothem est une CLI Python avec un petit ensemble de dépendances d'exécution, auxquelles s'ajoute une chaîne d'outils plus vaste de développement, d'audit, de publication et de documentation. Les dépendances d'exécution utilisent des bornes inférieures prudentes dans pyproject.toml ; le site web commite site/package-lock.json ; les GitHub Actions sont épinglées par SHA immuable avec des commentaires de version et sont mises à niveau par Dependabot.

Ratification de publicationCopy Anchor Link

VerrouillageCopy Anchor Link

Les fichiers de verrouillage Python propres aux contributeurs sont générés à la demande et ne sont pas commités : la fermeture d'exécution d'Apothem est petite et la CLI prend en charge plusieurs versions mineures de Python. La CI fait exception. Elle installe les fichiers verrouillés par hash de scripts/ci/ : quatre verrous de dépendances (requirements-ci-dev.txt, -runtime.txt, -test.txt et -prereqs.txt) et un verrou par outil qu'exécutent les flux de travail (-ruff.txt, -bandit.txt, -pip-audit.txt, -pip-licenses.txt et -pre-commit.txt). python scripts/dev/refresh_ci_locks.py compile les neuf à une date de verrouillage moins un délai d'attente de 7 jours, aligné sur celui de Dependabot : la CI teste donc les versions publiées depuis au moins une semaine à la date de verrouillage, et l'actualisation des fichiers les fait avancer. Chaque fichier consigne la date de verrouillage, le délai d'attente et la date limite qui en résulte, et --check reproduit cette date limite. Un correctif de sécurité urgent plus récent que le délai d'attente exige une actualisation avec --cooldown-days 0, ou une exception au délai d'attente pour son paquet dans scripts/dev/ci_lock_table.py, qui lève le délai pour ce seul paquet. L'exécution hebdomadaire de pip-audit.yml audite les versions les plus récentes qu'autorise pyproject.toml ainsi que les neuf verrous, en interrogeant le service OSV sur les avis de sécurité. Les contributeurs continuent d'installer avec 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

Le site web est différent : site/package-lock.json est commité et la CI utilise npm ci, de sorte que le site de documentation rendu possède une fermeture Node reproductible.

JustificationCopy Anchor Link

• Pourquoi des épinglages par plage pour Python ? La CLI prend en charge une large matrice Python, donc pyproject.toml garde des planchers prudents. La CI installe des fermetures verrouillées par hash de ces plages, que le mainteneur actualise avec scripts/dev/refresh_ci_locks.py (le rythme prévu est hebdomadaire), et l'exécution hebdomadaire de pip-audit.yml résout les versions autorisées les plus récentes pour révéler les problèmes avec l'outillage actuel.
• Pourquoi un verrou Node commité ? Le site web est un artefact statique déployé ; le fichier de verrouillage donne des builds npm ci déterministes pour cette surface publique.
• Pourquoi des Actions épinglées par SHA ? Les étiquettes sont mutables ; les SHA sont immuables. Dependabot propose les mises à niveau de SHA et réécrit chaque commentaire de version, tandis que le portail de publication consigne toute retenue intentionnelle.
• Ce que le robot de mise à jour ne touche pas. Les mises à jour de version de Dependabot (.github/dependabot.yml) couvrent les épinglages des GitHub Actions, le fichier de verrouillage du site web, le fichier de verrouillage de l'empaqueteur vsce (tools/vsce), le fichier de verrouillage des CLI de harnais qu'installe le channel smoke (tools/channel-smoke), le pip verrouillé par hash qu'installe la CI (scripts/ci/requirements-ci-pip.txt) et les hooks pre-commit. Les neuf autres fichiers de scripts/ci sont des fermetures régénérées en entier avec scripts/dev/refresh_ci_locks.py ; aucun n'épingle pip, et les mises à jour de version de Dependabot pour ce dossier se limitent à pip. Les planchers d'exécution de pyproject.toml, les exigences de publication verrouillées par hash, la fermeture vendorisée de src/apothem/_vendor/vendor.txt et les hooks pre-commit épinglés en phase avec pyproject.toml évoluent à la main, car la mise à niveau d'un seul épinglage casserait les fichiers avec lesquels ils concordent. Les hooks ruff et mypy en font partie : tests/scripts/test_ci_tool_locks.py échoue tant que l'épinglage exact de ruff dans pyproject.toml, la rev du hook, le verrou ruff et le verrou dev ne portent pas une seule et même version, et tant que l'épinglage exact de mypy, la rev du hook mypy et les bibliothèques que liste ce hook ne correspondent pas au verrou dev. Une pull request de sécurité Dependabot pour l'un ou l'autre outil s'adapte donc à la main. La version majeure de @types/node du site web suit son plancher Node (engines et .nvmrc, Node 22) ; Dependabot ne propose donc que ses mises à jour mineures et correctives ; relevez cette version majeure en même temps que le plancher. Les mises à jour de version laissent intacts les blocs npm overrides. Les mises à jour de sécurité de Dependabot couvrent toujours chaque manifeste, de sorte qu'une pull request de sécurité peut proposer l'un de ces épinglages, ou déplacer une surcharge ; adaptez-la à la main ou fermez-la.
• Fusionner une pull request Dependabot. Le squash par défaut du dépôt reprend le titre de la PR. Certains titres Dependabot, surtout des titres groupés qui nomment un répertoire, dépassent le sujet de squash de 72 caractères ; la vérification PR Title les signale, et un changement de titre les corrige. Une pull request qui modifie le fichier de verrouillage d'un outil n'exécute aucune tâche ci.yml ; le flux de travail d'audit npm l'audite et l'installe, empaquette l'extension VS Code pour le fichier de verrouillage vsce et exécute les tests de publication vsce, et le flux de travail channel smoke s'exécute pour le fichier de verrouillage channel-smoke. Le flux de travail Markdown Lint exécute le hook markdownlint sur une pull request de hooks pre-commit ; les autres hooks ne sont pas exercés en CI, alors exécutez pre-commit run --all-files sur sa branche avant de la fusionner.