Keep a Changelog, vraiment implémenté
6 min de lecture mis à jour le
Keep a Changelog est une convention d’une page pour un CHANGELOG.md : version la plus récente en
premier, une section par version avec un numéro et une date ISO, entrées regroupées sous six types
(Added, Changed, Deprecated, Removed, Fixed, Security), et une section Unreleased en haut pour les
entrées entre les versions. La plupart des équipes qui la citent en implémentent environ deux
tiers, et le tiers qu’elles laissent tomber est celui qui protège leurs utilisateurs.
Olivier Lacan a publié Keep a Changelog en 2014 avec une phrase qui a mieux vieilli que la plupart de la prose logicielle : don’t let your friends dump git logs into changelogs. Dix ans plus tard, c’est ce qui se rapproche le plus d’un standard dans ce coin du logiciel. Ça vaut la peine de lire la source plutôt qu’un résumé ; ceci traite des parties abandonnées.
Que demande Keep a Changelog ?
Un CHANGELOG.md à la racine du repo, le plus récent en premier, avec une section par version.
Chaque version porte un numéro et une date ISO, et regroupe ses entrées sous six types :
| Type | Pour | Ce que ça coûte de l’abandonner |
|---|---|---|
| Added | Nouvelles fonctionnalités | Rien ; personne n’abandonne celui-là |
| Changed | Changements de comportement existant | Les lecteurs découvrent un changement de comportement par une erreur |
| Deprecated | Fonctionnalités sur le point d’être supprimées | Une suppression devient un incident plutôt qu’un événement planifié |
| Removed | Fonctionnalités supprimées dans cette version | Personne ne distingue une suppression d’un bug |
| Fixed | Corrections de bugs | Rien ; personne n’abandonne celui-là non plus |
| Security | Vulnérabilités | La seule lectrice qui le cherchait ne le trouve pas |
Plus une section Unreleased en haut, pour qu’il y ait un endroit où mettre une entrée dès qu’elle
est mergée, et pour que n’importe qui puisse voir ce qui arrive.
C’est à peu près tout. Le reste, c’est le raisonnement : les entrées sont pour des humains, une entrée par changement, et le fichier est un document plutôt qu’un log.
Quelles parties de Keep a Changelog sont abandonnées ?
La section Unreleased, puis quatre des six types, Security parmi eux, dans cet ordre.
Unreleased disparaît en premier. C’est la section sans échéance, donc c’est celle dont
l’entretien s’arrête en premier, et une fois partie les entrées sont écrites au moment de la
version à partir de l’historique des commits. C’est précisément le dump de git log contre lequel la
spec avertit dès le départ, atteint progressivement.
Automatisation du changelog consiste surtout à garder cette
section vivante sans que personne ait à s’en souvenir.
Les six types s’effondrent en deux. La plupart des vrais changelogs finissent avec Added et Fixed, parce que Changed et Deprecated demandent un jugement sur ce que quelqu’un tenait pour acquis. Ce jugement est la partie précieuse. Deprecated en particulier est le seul type qui est une promesse sur l’avenir, et l’abandonner, c’est comment une suppression se transforme en incident ; la mécanique pour tenir cette promesse est dans comment déprécier une API.
Security cesse d’être séparé. Une correction de sécurité classée sous Fixed est invisible pour la seule lectrice qui la cherchait. Gardez-la distincte même quand la correction est triviale, et surtout quand vous préféreriez ne pas y attirer l’attention.
Que ne répond pas la spec ?
C’est un format de fichier. Elle ne dit rien sur les questions qu’on rencontre immédiatement après l’avoir adoptée :
- Comment quelqu’un l’apprend-il ? Un fichier dans un repo atteint les contributeurs. Il n’atteint pas une cliente qui n’a jamais ouvert GitHub.
- Et les produits sans versions ? Un service déployé en continu n’a pas de v4.2.0 pour regrouper. La plupart des équipes substituent des dates, ce qui fonctionne, et la spec ne l’approuve ni ne l’interdit.
- Qui écrit l’entrée ? La spec suppose qu’un humain le fait. Elle ne dit pas quand.
- Et les audiences multiples ? Un fichier sert les développeurs. Il ne sert pas le même contenu à une administratrice non technique, et le reformater à la main pour elle est où commence la duplication. Changelog vs release notes est la division que la spec vous laisse faire vous-même.
Common Changelog, un fork plus strict de l’idée, resserre une partie de ça : il interdit certaines formulations d’entrées, exige un lien vers le changement, et a un avis tranché sur qui est le lecteur. Ça vaut la peine à lire si les parties floues de Keep a Changelog sont ce sur quoi votre équipe n’arrête pas de se disputer.
Peut-on automatiser Keep a Changelog sans dumper des git logs ?
Oui : dérivez le brouillon de commits structurés, mettez-le dans Unreleased avec son type pré-rempli, et exigez qu’un humain édite la formulation avant qu’une version soit taillée. L’avertissement de la spec concerne le résultat, pas l’outillage. Dériver un brouillon de commits, c’est correct. Publier ce brouillon non édité est ce à quoi elle s’oppose.
La machine gère la collecte et le formatage, ce en quoi elle est bonne. L’humain gère la sélection et la formulation, ce en quoi elle ne l’est pas. Conventional commits couvre la séparation en deux couches sur laquelle ça repose, et quels types de commit correspondent à quelles des six catégories ci-dessus. Notre récap outils de changelog couvre ce qui existe pour la moitié collecte.
Où Keep a Changelog cesse-t-il d’être suffisant ?
Ça s’arrête à la distribution. Keep a Changelog est une bonne réponse à “à quoi devrait ressembler ce fichier”. Ce n’est pas une réponse à “comment nos utilisateurs apprennent-ils ce qui a changé”, parce qu’un fichier Markdown dans un repo est une stratégie de distribution qui ne fonctionne que si vos utilisateurs sont des contributeurs.
C’est l’obstacle que la plupart des équipes rencontrent en second : le fichier va bien, et personne en dehors de l’équipe ne le lit. Le résoudre signifie que les entrées doivent devenir des données qui peuvent être rendues ailleurs, ce qui est un problème différent de formater un fichier, et la raison pour laquelle exemples de changelog rassemble des pages publiques de changelog plutôt que des fichiers de repository. Comment transformer ces entrées en quelque chose auquel les gens reviennent est couvert dans construire une page de changelog.
Adoptez quand même la spec. Ça coûte un après-midi, ça rend le second problème traitable, et c’est toujours la meilleure page jamais écrite sur ce sujet.
FAQ
Keep a Changelog est-il un standard ? C’est une convention largement adoptée, pas la spécification d’un organisme de normalisation. Les outils (scripts de release, linters, parsers) supposent souvent sa forme, au point que la suivre achète de la compatibilité.
Que met-on dans la section Unreleased ? Chaque entrée pour un changement qui a été mergé mais pas encore livré dans une version numérotée. Quand une version est taillée, la section est renommée avec la version et la date, et une nouvelle section Unreleased vide se place au-dessus.
Un changelog devrait-il utiliser le versionnage sémantique ? Keep a Changelog le recommande et ne l’exige pas. Les bibliothèques et les API en bénéficient ; un service déployé en continu substitue généralement des dates, ce que le format accommode.
Les corrections de sécurité devraient-elles être dans le changelog avant d’être publiques ? Ajoutez l’entrée quand la correction est livrée, avec assez de détail pour qu’une opératrice puisse agir et pas plus. Retarder l’entrée jusqu’à une date de divulgation coordonnée est normal ; l’omettre ne l’est pas.
Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.