Formats de fichier changelog : JSON, YAML ou juste Markdown
6 min de lecture
La plupart des équipes commencent un changelog comme fichier Markdown parce que c’est le chemin de moindre résistance : lisible dans le diff d’une pull request, lisible sur GitHub sans rien rendre, et familier pour quiconque a déjà écrit un README. Ce choix fonctionne bien jusqu’à ce que quelque chose d’autre qu’une personne doive lire le fichier, une page, un widget, un digest email, et alors le format cesse d’être gratuit. Automatisation du changelog couvre l’exigence structurelle en général, un type, une date, un corps et un lien ; ceci porte sur quel format de fichier livre réellement cette structure et ce que chacun coûte pour y arriver.
Qu’est-ce qui ne va pas avec un changelog Markdown simple ?
Rien, jusqu’à ce que quelque chose doive le reparser en champs. Un titre, une date et une liste à puces en dessous est trivial à lire pour une personne et vraiment difficile à parser de façon fiable, parce que Markdown n’a pas de schéma : la date pourrait être dans le titre, en gras sur la première ligne, ou totalement absente sur une vieille entrée, et chacune de ces variantes est du Markdown valide qu’une personne lit correctement et qu’un parser non. Les équipes qui automatisent un changelog Markdown finissent généralement par écrire un parser maison basé sur des regex qui casse la première fois que le formatage d’une entrée dérive même légèrement, ce qui arrive souvent, parce que rien n’impose de cohérence à l’écriture.
Qu’est-ce qu’un format structuré apporte réellement ?
Une garantie que chaque entrée a la même forme, vérifiée quand l’entrée est écrite plutôt que devinée quand elle est lue. Un fichier JSON ou YAML avec un schéma défini, type, date, version, audience, corps, lien, échoue bruyamment si un champ requis manque, de la même façon qu’une réponse d’API stricte le ferait ; un fichier Markdown rend simplement ce qui est là, correct ou non. Cette différence est invisible jusqu’au jour où un script a besoin de la date de chaque entrée pour trier un flux, et où la moitié des entrées l’ont à un endroit différent.
# CHANGELOG.yml
- date: 2026-09-05
type: breaking
version: v2
audience: api
body: "POST /invoices now rejects a currency mismatch instead of silently converting."
link: /blog/api-changelog/Ça veut dire que le fichier lisible par l’humain doit disparaître ?
Non, et essayer de faire jouer à un fichier YAML ou JSON le double rôle de ce qu’une personne lit dans une pull request est généralement une erreur dans l’autre sens : revoir un diff de JSON imbriqué est pire que revoir une phrase de prose, et une relectrice qui doit parser mentalement une structure de données pour repérer une erreur de formulation est une relectrice qui finira par arrêter de repérer les erreurs de formulation. Les deux formats peuvent coexister : les données structurées sont la source de vérité que lit un pipeline d’automatisation, et un rendu Markdown ou HTML généré est ce qu’une personne relit et lit réellement, produit à partir du fichier structuré plutôt que maintenu à la main à côté.
| Format | Lisible par l’humain tel quel | Parsable par machine sans code sur mesure | Mode d’échec courant |
|---|---|---|---|
| Markdown | Oui | Non | Forme d’entrée incohérente casse les parsers naïfs |
| JSON | Faible | Oui | Verbeux ; facile à éditer à la main vers du JSON invalide |
| YAML | Correct | Oui | Sensible aux espaces ; une mauvaise indentation est une erreur de parsing silencieuse, pas bruyante |
Quel format structuré est en réalité plus facile à éditer à la main, JSON ou YAML ?
YAML, pour quiconque écrit des entrées à la main plutôt que via un générateur, parce qu’il élimine le quoting et l’appariement d’accolades que JSON exige pour chaque chaîne et objet imbriqué. Le compromis est que la sensibilité de YAML aux espaces échoue silencieusement d’une façon dont les désaccords d’accolades de JSON ne le font généralement pas : un parser JSON rejette d’emblée une entrée mal formée, tandis qu’un parser YAML peut accepter un fichier mal indenté et simplement le parser dans la mauvaise structure, ce qui est un échec pire parce que rien ne vous dit que c’est arrivé. Si les entrées ne sont jamais écrites que par un script, ce compromis disparaît largement et le parsing plus strict de JSON devient le choix par défaut le plus sûr.
Une page de changelog a-t-elle besoin de son propre format structuré, séparé du fichier qui l’alimente ?
Pas un séparé, le même rendu différemment. Une page de changelog couvre comment rendre la page elle-même lisible par machine via un flux JSON et un balisage schema.org ; ce flux est une sortie générée, pas une seconde source de vérité à garder synchronisée avec le fichier sous-jacent. Maintenir des données structurées à la main à deux endroits, un fichier source et le flux d’une page, est comment les deux finissent par diverger, donc la décision de format de fichier prise ici devrait être la seule chose dont tout ce qui suit, page, widget, email, est généré, jamais copié à la main.
Le coût de migration en vaut-il la peine pour convertir un changelog Markdown existant en format structuré ?
Généralement seulement une fois que l’automatisation est l’objectif réel, pas avant. Un projet d’une seule personne publiant un fichier Markdown dans un README GitHub n’a pas de vrai besoin d’automatisation, et le convertir en YAML n’achète rien d’autre que de la cérémonie. La conversion se rembourse d’elle-même au moment où plus d’un consommateur en aval, une page, un email de digest, un flux public, a besoin de lire les mêmes données, parce que c’est exactement le point où les incohérences d’un parser Markdown commencent à produire une sortie visiblement fausse au lieu d’être juste pénibles à maintenir.
FAQ
Un changelog Markdown peut-il être rendu parsable sans changer complètement de format ? Partiellement, avec du frontmatter : un petit bloc YAML en haut de chaque entrée (date, type, version) à côté d’un corps Markdown pour la prose. Ça obtient les champs structurés dont un parser a besoin sans forcer toute l’entrée en JSON ou YAML, et c’est un terrain d’entente raisonnable pour une équipe pas encore prête pour une migration complète.
Le format du fichier compte-t-il pour le SEO ou pour le classement d’une page de changelog ? Pas directement. Les moteurs de recherche lisent la page rendue, pas le fichier source, donc le format du fichier leur est invisible ; ce qui compte pour la page elle-même est si elle est lisible par machine de son propre droit, ce qui est une question séparée de ce qui la génère.
Chaque entrée de changelog devrait-elle passer par le même fichier, ou les types peuvent-ils être répartis sur plusieurs fichiers ? Un seul fichier est plus simple jusqu’à ce que le volume d’entrées le rende difficile à differ ou relire ; diviser par année ou par catégorie est une soupape de sécurité raisonnable une fois que les diffs d’un seul fichier deviennent trop gros pour être relus sensément, mais ça ajoute une étape de fusion avant que quoi que ce soit en aval puisse lire « toutes les entrées » comme une seule liste.
Existe-t-il un format de fichier changelog standard, comme il existe un standard pour RSS ? Pas un largement adopté. Keep a Changelog propose une convention Markdown, et plusieurs outils ont le leur ; un changeset est un fichier Markdown avec un frontmatter YAML qui nomme le package et le saut de version, ce qui est le modèle de frontmatter décrit plus haut. Aucun n’est un format que d’autres outils lisent d’emblée comme les lecteurs RSS comprennent RSS universellement.
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.