Skip to content
Apothem
Gouvernance

Politique d'ingénierie de publication

Cinq politiques canoniques pour le versionnage, l'étiquetage des publications, les cycles d'obsolescence, les changements incompatibles et les procédures de retour arrière.

Cinq politiques régissent la façon dont apothem est publié.

1. Versionnage sémantique

Le projet est distribué sous Semantic Versioning 2.0. Les numéros de version prennent la forme MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD].

IncrémentDéclencheurs
MAJORChangements incompatibles dans les schémas d'artefacts, les identifiants de mandat (CM-N / TM-N / CP-N) ou les contrats de hooks
MINORNouvelles règles, travailleurs délégués, commandes, skills, événements de hook ou extensions de schéma non incompatibles
PATCHClarifications, ajouts d'anti-modèles, corrections de documentation, modifications qui ne changent pas le comportement

Les étiquettes candidates utilisent le format vX.Y.Z-rc.N (candidate à la publication) ou vX.Y.Z-alpha.N / vX.Y.Z-beta.N (accès anticipé).

2. Étiquettes de publication

Chaque publication dépose sur main une étiquette git signée de la forme vMAJOR.MINOR.PATCH. L'étiquette déclenche .github/workflows/release.yml, qui compile, signe, génère le SBOM et la provenance SLSA-3, et publie la page GitHub Release.

Conventions d'étiquetage :

  • Format — exactement vMAJOR.MINOR.PATCH. Pas de préfixe release-, pas de suffixe -final.
  • Annotation — chaque étiquette est une étiquette annotée (git tag -a -s) qui porte le résumé des notes de publication dans le message de l'étiquette.
  • Signature — chaque étiquette est signée avec GPG. Le flux de travail de publication produit en outre une signature cosign Sigstore sans clé sur chaque artefact et un enregistrement de provenance SLSA-3, tous deux joints à la page GitHub Release.

Modèle de publication : additif

Les publications sont additives. Chaque publication ajoute un commit sur main et une étiquette ; main ne fait jamais l'objet d'un force-push, et aucun élément publié (étiquette, GitHub Release ou version npm) n'est supprimé, déplacé ni réutilisé. Chaque publication conserve son étiquette, son GitHub Release et sa version npm, et toutes restent publiées. Les versions npm sont immuables : un name@version publié ne peut jamais être remplacé, et un numéro dépublié ne peut jamais être réutilisé. Les installations épinglées et les compilations reproductibles dépendent de chaque étiquette publiée. Les runbooks de cycle de publication et de récupération de publication suivent tous deux ce modèle.

La règle de façade de publication du dépôt (la section Release Facade des instructions destinées aux contributeurs) énonce ce modèle. Son exigence de n'afficher que la version courante, reprise dans la règle de façade de fraîcheur, porte sur ce qu'affichent les surfaces publiques. Elle ne limite pas les publications qui restent publiées.

3. Politique d'obsolescence

La ligne de support public actuelle est la dernière version mineure publiée. Lorsque le projet comporte plusieurs versions mineures publiques, la matrice des versions prises en charge de SECURITY.md fait foi pour toute fenêtre de support supplémentaire limitée aux correctifs critiques.

Cadence d'obsolescence :

  • Annonce — un symbole ou un comportement obsolète est annoncé dans la section ### Deprecated du CHANGELOG.md de la publication dans laquelle l'obsolescence intervient. Les notes de publication reprennent l'annonce d'obsolescence.
  • Fenêtre de grâce — les symboles obsolètes restent disponibles pendant au minimum un cycle mineur complet avant leur suppression.
  • Suppression — la suppression intervient lors d'un incrément MAJOR. Chaque symbole supprimé porte une ligne ### Removed dans CHANGELOG.md et une entrée de guide de migration sous Guides pratiques.

Planchers d'exécution

Apothem déclare deux planchers d'exécution : requires-python = ">=3.10" dans pyproject.toml et "engines": {"node": ">=18"} dans package.json.

  • Chaque plancher déclaré est testé. Le plancher Python s'exécute dans la matrice CI quality et dans le flux de travail CI Matrix. Le flux de travail npm Shim exécute le shim npm sur le plancher Node et sur chaque version majeure LTS ultérieure : il vérifie l'erreur de prérequis manquant, node bin/apothem.mjs --version, une installation à blanc dans un répertoire personnel isolé, et l'archive tar empaquetée via npx. Un runtime qui n'est pas testé n'est pas déclaré.
  • La fin de vie est signalée. Lorsqu'un runtime qui est encore un plancher déclaré atteint sa fin de vie en amont, le guide d'installation l'indique et nomme les versions à privilégier. Python 3.10 a atteint sa fin de vie le 2026-10-01 ; Node.js 18 et 20 le 2025-04-30 et le 2026-04-30. Les trois restent des planchers pris en charge.
  • Relever un plancher constitue une obsolescence. Cela suit la cadence ci-dessus : une annonce sous ### Deprecated, au moins un cycle mineur complet pendant lequel l'ancien plancher reste testé, puis la publication qui le relève consigne le changement. requires-python, engines.node, les sondes de version des installateurs et les matrices CI changent ensemble dans cette publication.

4. Politique de changements incompatibles

Les changements incompatibles exigent :

  1. Un ticket RFC — ouvert avec l'étiquette de ticket rfcs, qui décrit le changement incompatible, le chemin de migration et la stratégie de retour arrière.
  2. Une fenêtre de commentaires de 30 jours — la RFC reste ouverte pendant au moins 30 jours avant la fusion. Les mainteneurs peuvent prolonger la fenêtre lorsque les retours le justifient.
  3. Un incrément MAJOR — la publication qui introduit le changement incompatible incrémente le composant MAJOR.
  4. Un guide de migration — le changement est livré avec une entrée de Guides pratiques qui guide l'opérateur tout au long de la migration.

5. Politique de retour arrière

Si une publication présente une régression qui bloque l'adoption :

  1. Annulation — le ou les commits fautifs sont annulés sur main.
  2. Publication corrective vers l'avant — une publication de suivi intervient sous vMAJOR.MINOR.PATCH+1 et porte l'annulation ainsi que toute correction incrémentale. La précédente publication défectueuse n'est pas supprimée de GitHub Releases, et sa version npm reste publiée (les versions npm sont immuables) et est marquée avec npm deprecate. Une annotation ### Yanked dans CHANGELOG.md documente la situation afin que les compilations reproductibles restent ancrées.
  3. Communication — un avis security-advisories (lorsqu'il est pertinent pour la sécurité) ou un ticket GitHub épinglé pour l'incident (lorsqu'il est pertinent pour la fiabilité) accompagne le retour arrière.

Voir aussi

  • CHANGELOG.md — le registre canonique des publications.
  • SECURITY.md — la matrice des versions prises en charge et les canaux de signalement.
  • cicd-pipeline.md — les classes de vérifications CI qui contrôlent chaque publication.
  • deployment-checklist.md — le balayage de préparation à la production effectué pour chaque publication.

Registre de conformité externe — Lors d'opérations sur des projets hôtes

Registre de quinze mandats (M1–M15) spécifiant les exigences de conformité pour tous les artefacts générés dans les projets hôtes, croisé avec les mandats internes à l'écosystème.

Politique des badges

Spécifier les sources de badges dynamiques et statiques du README, en couvrant le statut de flux de travail natif GitHub, le JSON d'endpoint shields.io et les formes de badge statique.

On this page

1. Versionnage sémantique2. Étiquettes de publicationModèle de publication : additif3. Politique d'obsolescencePlanchers d'exécution4. Politique de changements incompatibles5. Politique de retour arrièreVoir aussi