Conventions de changelog
Conventions de changelog
Section intitulée « Conventions de changelog »Cette page est le contrat que suit chaque dépôt public NextPDF lorsqu’il consigne un changement et publie une version. C’est une référence de convention ; elle ne décrit aucun comportement propre aux paquets. Le texte spécifique à chaque paquet et à chaque version se trouve dans le CHANGELOG.md du dépôt concerné. Cette page définit leurs règles communes, afin que le résumé de changelog inter-dépôts soit cohérent et exempt de fuite interne.
Conventional Commits 1.0.0
Section intitulée « Conventional Commits 1.0.0 »Chaque sujet de commit a la forme type(scope): description. Le type est l’un des suivants :
| Type | Signification | Visible par l’utilisateur | Effet sur la version |
|---|---|---|---|
feat | Nouvelle fonctionnalité | oui | incrément mineur |
fix | Correction d’un comportement | oui | incrément correctif |
perf | Amélioration de performance sans changement de comportement | oui | incrément correctif |
refactor | Restructuration interne sans changement observable | non | aucun |
docs | Documentation uniquement | non | aucun |
test | Tests uniquement | non | aucun |
build / ci | Compilation ou pipeline uniquement | non | aucun |
chore | Maintenance, dépendances et outillage | non | aucun |
revert | Annule un commit antérieur | selon le cas | selon le cas |
Un changement incompatible est signalé par un ! après le type ou le scope (feat(api)!: …) ou par un pied de page BREAKING CHANGE:. L’un ou l’autre déclenche un incrément majeur selon Semantic Versioning. Un correctif de sécurité est enregistré de façon à pouvoir être filtré vers la colonne Security du résumé inter-dépôts.
Semantic Versioning 2.0.0
Section intitulée « Semantic Versioning 2.0.0 »Le changement de version est mécanique. Une version qui contient le moindre changement incompatible est une majeure. À défaut, une version contenant au moins un feat est une mineure. À défaut, une version contenant au moins un fix ou un perf est un correctif. Les paquets pré-1.0 peuvent incrémenter la mineure pour un changement incompatible, conformément au §4 de SemVer. Le commit porte néanmoins le marqueur d’incompatibilité afin que le résumé reste exact.
Regroupement Keep a Changelog
Section intitulée « Regroupement Keep a Changelog »Le CHANGELOG.md de chaque dépôt suit Keep a Changelog 1.1.0 : les entrées sont regroupées par version publiée sous Added, Changed, Deprecated, Removed, Fixed et Security. Une section [Unreleased] peut contenir des notes de travail en cours dans le dépôt, mais le résumé inter-dépôts ne prend en compte que les versions étiquetées et publiées. Le travail non publié n’apparaît jamais dans l’index public.
Comment le résumé inter-dépôts est dérivé (et maintenu exempt de fuite)
Section intitulée « Comment le résumé inter-dépôts est dérivé (et maintenu exempt de fuite) »Le tableau récapitulatif de l’index du changelog est produit en lisant, en lecture seule, l’historique Conventional Commits de chaque dépôt jusqu’à son dernier tag publié, puis en comptant les catégories. Les règles de dérivation sont volontairement strictes pour qu’aucun détail interne ne puisse s’échapper :
- Des décomptes, pas du contenu. Seul le nombre de commits par type visible par l’utilisateur est indiqué. Aucun sujet, corps, pied de page ni hachage de commit n’est rendu.
- Types visibles par l’utilisateur uniquement.
docs,test,ci,choreetrefactorsont exclus : ils ne changent rien de ce qu’observe un consommateur du paquet. - Publié uniquement. Un commit ne compte qu’une fois qu’il fait partie d’une version étiquetée d’un paquet public.
- Aucun identifiant. Les références internes à un incident, un ticket, un cycle, une vague ou un élément de travail susceptibles d’apparaître dans un scope de commit privé ne sont jamais exposées, car le texte du scope lui-même n’est jamais rendu : seul le type est lu.
- Aucune attribution d’automatisation. Les en-têtes d’automatisation liés aux contributeurs ne sont ni lus ni affichés.
C’est pourquoi le changelog public est un résumé par catégorie, assorti de liens vers le CHANGELOG.md propre à chaque paquet, plutôt qu’un flux agrégé de commits. Par construction, le résumé est démontrablement exempt de toute fuite interne. Le texte faisant autorité reste dans le paquet qui en a la responsabilité.