guides

Un changelog est un fichier qui liste les changements notables apportés à un projet, organisés par version. Son rôle est de répondre à une question simple pour toute personne qui utilise votre logiciel ou en dépend : qu'est-ce qui a changé entre la version que j'avais et celle vers laquelle je passe. Comme il est écrit pour des humains et non pour des machines, un bon changelog met en avant ce qui compte réellement pour les utilisateurs et laisse de côté le bruit.

Il est utile de préciser ce qu'un changelog n'est pas. Ce n'est pas la sortie brute de votre historique de gestion de versions. Un git log liste chaque commit, y compris les petits refactors, les corrections de fautes de frappe et les commits de fusion, dans l'ordre où ils ont été faits et avec la formulation choisie par l'auteur. Un changelog est un résumé trié, rédigé par un humain, qui regroupe les travaux liés, écarte les détails triviaux et décrit chaque changement en fonction de son effet sur la personne qui le lit.

La convention la plus suivie pour en écrire un s'appelle Keep a Changelog. Elle définit un format simple fondé sur Markdown, généralement dans un fichier nommé CHANGELOG.md à la racine du dépôt. L'idée est qu'une structure cohérente et prévisible rend le fichier facile à parcourir, que le lecteur soit une personne naviguant sur un hébergeur de code ou un outil qui analyse les entrées.

Le format Keep a Changelog

Selon cette convention, chaque version publiée obtient sa propre section, intitulée par le numéro de version et la date de publication. Au sein d'une version, les changements sont regroupés sous un petit ensemble d'intitulés standard pour que les lecteurs trouvent vite ce qui les intéresse. Les groupes recommandés sont Added pour les nouvelles fonctionnalités, Changed pour les modifications de comportement existant, Deprecated pour les fonctionnalités en voie de disparition, Removed pour celles qui ont été retirées, Fixed pour les corrections de bugs et Security pour tout ce qui touche aux vulnérabilités.

Les versions elles-mêmes suivent le plus souvent le versionnage sémantique, si bien qu'une version se lit MAJEUR.MINEUR.CORRECTIF, comme 2.4.1. Cela relie le changelog au numéro de version de façon utile : un lecteur peut regarder le saut d'une version à la suivante et se faire une idée. Un changement du numéro majeur signale que quelque chose peut casser, tandis qu'une hausse de correctif suggère seulement des corrections. Le changelog explique ensuite, en mots, ce qui se cache exactement derrière ce numéro.

Ordre, dates et section Unreleased

Un changelog est normalement tenu dans l'ordre chronologique inverse, la version la plus récente en haut, de sorte que l'information la plus pertinente soit la première que voit le lecteur. Chaque entrée est datée, ce qui permet de situer une publication dans le temps et de comprendre à quel point une correction ou une fonctionnalité est récente. Garder l'ordre et les dates cohérents fait partie de ce qui rend le fichier fiable au premier coup d'oeil.

• Un changelog est un fichier listant les changements notables de chaque version, écrit pour des humains, pas le git log brut.
• Keep a Changelog est la convention courante, en général un CHANGELOG.md en Markdown à la racine du dépôt.
• Groupes de changements standard : Added, Changed, Deprecated, Removed, Fixed et Security.
• Les versions suivent en général le versionnage sémantique (MAJEUR.MINEUR.CORRECTIF), chacune avec sa date de publication.
• Les entrées vont dans l'ordre chronologique inverse, souvent avec une section Unreleased en haut.
• On peut générer les entrées depuis les commits (par exemple Conventional Commits), mais un changelog écrit à la main est souvent plus clair.

Un ajout courant et pratique est une section Unreleased tout en haut. C'est là que vous consignez les changements au fur et à mesure, avant qu'ils ne soient liés à un numéro de version. Quand vous êtes prêt à publier une version, vous renommez cette section avec le nouveau numéro, lui donnez une date et démarrez un nouveau bloc Unreleased. Cette habitude fait que le changelog est écrit pendant que le travail est frais, plutôt que reconstitué de mémoire à la dernière minute.

Bien rédiger les entrées et les générer

Bien rédiger les entrées revient surtout à garder le lecteur à l'esprit. Chaque changement notable devrait avoir sa propre entrée, formulée pour que quelqu'un qui ne connaît pas les rouages internes en comprenne quand même l'effet. Il vaut mieux décrire le résultat pour l'utilisateur plutôt que la mécanique du code, éviter le jargon interne et regrouper les modifications liées en une seule ligne claire plutôt qu'une entrée par commit. Les changements triviaux ou purement internes peuvent être totalement omis.

Il est possible de générer un changelog automatiquement à partir de votre historique de commits, et beaucoup d'équipes le font. Des approches comme Conventional Commits vous demandent d'écrire les messages de commit de façon structurée, par exemple en les préfixant par feat ou fix, pour qu'un outil puisse les trier dans les bons groupes et assembler un brouillon. Cela peut faire gagner du temps et imposer de la cohérence, mais le résultat tend à se lire comme une liste de commits. Un changelog écrit ou au moins relu à la main est souvent plus clair, car une personne peut décider de ce qui mérite d'être mentionné et le formuler pour son public.

En résumé

En résumé, un changelog est un enregistrement lisible de ce qui a changé dans chaque version d'un projet, tenu pour les personnes qui l'utilisent. La convention Keep a Changelog lui donne une forme prévisible, le versionnage sémantique donne un sens à ses numéros de version, et un peu de discipline, comme une section Unreleased et une entrée par changement notable, le garde exact. Qu'il soit écrit à la main ou généré à partir des commits, sa valeur vient de sa clarté, de son actualité et de sa concentration sur ce que le lecteur a réellement besoin de savoir.