Ce qui est lu
Quels titres deviennent des versions, lesquels des groupes, et ce qu’il advient du reste.
L’analyseur lit un journal des versions comme une suite plate de titres et décide ce qu’est chacun. Rien n’est configuré : l’entrée est la forme du fichier lui-même.
Un titre de version
Un titre est une version quand — tout lien réduit au texte qu’il affiche — ce qui reste est un numéro de version, éventuellement suivi d’une date entre parenthèses.
## [1.4.0](https://github.com/acme/app/compare/v1.3.0...v1.4.0) (2026-02-01)
### [1.4.1](https://github.com/acme/app/compare/v1.4.0...v1.4.1) (2026-02-03)
## 1.4.0 (2026-02-01)
## v2.0.0
Les quatre se lisent. Les deux premiers sont ce qu’écrit release-please — une
version mineure en ## et un correctif en ### — et les deux derniers un fichier
tenu à la main. Le niveau ne fait pas partie du test, et c’est ce qui laisse passer
les deux formes.
Le niveau se lit sur le corps plutôt que d’être supposé, pour la même raison :
release-please écrit un correctif en ### et ses groupes en ### également, si
bien que « le titre le moins profond de cette version » est la seule règle qui lise
les deux.
Un titre de groupe
Tout titre sous le niveau de la version est un groupe, et son nom est celui du fichier — mot pour mot, non traduit, sans taxonomie fixe derrière.
### Features
### Bug Fixes
release-please écrit ces deux-là, changesets écrit son propre jeu, Keep a Changelog un autre, et chacun les écrit dans la langue où le projet est tenu. Une couche qui les rabattrait sur une liste fixe échouerait en silence au premier titre inconnu — les filtres de la vue d’ensemble sont donc construits à partir de ce qui est sorti du fichier, et un journal écrit en allemand filtre en allemand sans rien configurer.
Le badge à côté d’un groupe compte ses éléments de liste de premier niveau. Un titre à l’intérieur d’un bloc de code est du texte et non un titre, et une clôture ne se ferme que sur la sienne.
Le titre et le préambule
Le premier # du fichier, si aucune version ne l’a précédé, est le titre propre du
fichier et il est retiré — la page tire son titre de title, le garder serait donc
un second <h1>.
Celui-là seulement, et seulement avant la première version. Retirer tous les
# se lit correctement sur le fichier qu’écrit release-please, où il y en a
exactement un, et c’est une perte de contenu silencieuse sur un journal tenu à la
main qui met ses versions au premier niveau.
Ce qui se trouve par ailleurs avant la première version reste, comme introduction propre de la vue d’ensemble.
Un titre qui est presque une version
La tolérance ci-dessus a un bord silencieux : un titre que le test de version ne reconnaît pas est de la prose, ses lignes se replient donc dans la version au-dessus, et la version qu’il devait être ne devient jamais une page. Rien du site rendu ne le dirait.
Alors le build le dit. Un titre qui ouvre sur un nombre à points mais ne se lit pas
— ## 1.4 (Feb 2024), ou la forme Keep a Changelog ## [1.2.3] - 2024-01-01 — est
signalé dans le rapport de build, avec la ligne et la forme qui marche.
C’est un avertissement et non un échec, pour la raison qui vaut pour tout constat de contenu : le site se rend, et un journal des versions que cette couche n’a pas écrit n’est pas au build de le rejeter. Voir Ce que le build vérifie.
L’URL à laquelle une version est servie
Le numéro de version, avec un v devant lorsqu’il commence par un chiffre.
/releases/v1.4.0
Le v n’est pas décoratif. Content lit un nom de fichier fait uniquement de
chiffres et de points comme une version et cesse de l’affiner, ce qui laisserait le
préfixe d’ordre dans l’adresse : /releases/01.0.2.0. Avec le v, le préfixe est
retiré comme partout ailleurs, et le segment correspond au tag sous lequel la
version a été coupée.