Modèle de release notes

Le modèle

Tout ce qui est entre crochets est un espace réservé. Tout le reste mérite d'être gardé, y compris l'ordre : le lecteur cherche ce qui le concerne, donc les changements importants viennent en premier et le travail interne n'apparaît pas.

## [Produit] [version] - [date]

[Une phrase sur l'objet de cette version. À omettre pour les versions de routine.]

### Changements importants
- [Ce qui cesse de fonctionner, quoi faire à la place, et d'ici quand.
  Lie les étapes de migration.]

### Nouveautés
- [Fonctionnalité, décrite comme un résultat. « Épingle un filtre et
  réutilise-le », pas « ajout du modèle SavedView ».]

### Améliorations
- [Ce qui est plus rapide, plus clair ou plus fiable, et de combien environ.]

### Corrections
- [Le symptôme observé par l'utilisateur, pas la cause dans le code.]

Si une section est vide, supprime le titre. Une section Corrections vide donne l'impression que rien n'a été corrigé, et un titre sans contenu fait penser que la page a mal chargé.

Le même modèle, rempli

Voici à quoi ça ressemble avec du vrai contenu. Remarque qu'aucune entrée ne nomme un fichier, une branche, un numéro de ticket ou une personne, et que le changement important commence par l'action que le lecteur doit accomplir.

## Acme API 4.2 - 20 août 2026

La pagination utilise désormais un curseur sur tous les endpoints de liste.

### Changements importants
- `?page=` est supprimé sur tous les endpoints de liste. Utilise la valeur
  `nextCursor` de la réponse précédente. `?page=` renverra 400 après
  le 1er octobre 2026. Étapes de migration :
  acme.example/docs/pagination

### Nouveautés
- Vues enregistrées dans la boîte. Épingle un filtre une fois et
  réutilise-le depuis la barre latérale.
- Les webhooks peuvent désormais être limités à un seul projet.

### Améliorations
- Les endpoints de liste répondent environ quatre fois plus vite sur
  les gros comptes.
- Le job d'export indique sa progression au lieu de sembler bloqué.

### Corrections
- Les membres invités ne voient plus un tableau de bord vide avant
  leur première connexion.
- Les horodatages des exports respectent désormais le fuseau horaire
  du compte.

Ce qui va dans chaque section

Changements importants

La seule section avec une échéance. Dis ce qui cesse de fonctionner, quoi faire à la place, et à partir de quelle date. Si tu n'as pas encore décidé de la date, ne publie pas encore la section : un changement important sans date se lit comme urgent, et une série de fausses urgences apprend aux gens à ignorer tes release notes.

Nouveautés

Décris le résultat, pas ce que tu as construit. Le test consiste à voir si la ligne a encore du sens pour quelqu'un qui n'a jamais vu ton code. « Vues enregistrées dans la boîte » réussit ce test. « Ajout du modèle SavedView et de sa migration » non.

Améliorations

Quantifie quand tu peux le faire honnêtement. « Plus rapide » ne vaut presque rien et est ignoré ; « environ quatre fois plus rapide sur les gros comptes » mérite d'être lu et fixe une attente dont on peut te tenir responsable. Si tu ne peux pas le mesurer, dis ce qui est meilleur de façon vérifiable.

Corrections

Écris le symptôme, pas la cause. Les gens cherchent dans ces notes ce qui leur est arrivé, donc « les membres invités voyaient un tableau de bord vide » est trouvable, et « correction d'une race condition dans le cache d'appartenance » ne l'est pas.

Variantes

Les quatre sections conviennent à la plupart des versions. Trois cas demandent un ajustement :

• Versions d'applications mobiles. Les app stores affichent un champ de nouveautés court, commence donc par une phrase lisible dans la fiche du store, puis renvoie vers les notes complètes. La revue du store peut aussi retarder une version de plusieurs jours, date donc les notes par date de sortie, pas de fusion.
• Versions d'API. Versionne les notes comme tu versionnes l'API, et mets la fenêtre de dépréciation dans les notes elles-mêmes, pas seulement dans la documentation. Qui consomme une API lit les notes précisément pour savoir combien de temps il lui reste.
• Outils internes ou d'administration. Supprime la section Améliorations et fusionne-la avec Corrections. Les utilisateurs internes se soucient de savoir si leur flux de travail a changé, et une longue section Améliorations noie cette information.

Quatre règles qui les gardent lisibles

1. Écris pour quelqu'un qui ne connaît pas ton code. Pas de noms de fichiers, pas de noms de branches, pas d'ids de tickets, pas de noms de services, pas de noms de code internes.
2. Omets tout ce qui n'a aucun effet visible pour l'utilisateur. Les montées de dépendances, les refactors, les changements de CI et les corrections de fautes de frappe vont dans l'historique des commits, pas dans les release notes. La façon la plus courante dont les release notes meurent, c'est en se remplissant de travail que personne en dehors de l'équipe ne peut voir.
3. Une entrée, un changement. Si une ligne a besoin du mot « et » deux fois, ce sont probablement deux entrées.
4. Publie à un rythme sur lequel les gens peuvent compter, même si ce rythme est « à chaque fois qu'on livre ». Des notes qui apparaissent quatre fois en une semaine puis plus pendant deux mois sont perçues comme du bruit.

Format des release notes : les parties, dans l'ordre

Le format compte moins que l'ordre. Quel que soit le style de titres que tu utilises, un lecteur qui parcourt des release notes cherche les quatre mêmes choses dans la même séquence, et tout format populaire en est une variation.

1. Un titre qui dit ce qui a changé pour le lecteur, pas le numéro de version. La version va sur une ligne plus discrète en dessous, avec la date au format ISO (2026-08-29) pour qu'elle se lise de la même façon partout.
2. Les changements importants et tout ce qui a une échéance, en premier, même petits. Si quelqu'un arrête de lire après un paragraphe, c'est celui-là qu'il lui fallait.
3. Les nouveautés, un point par paragraphe, avec le résultat dans la première phrase et l'action requise, y compris « aucune action nécessaire », toujours indiquée.
4. Corrections et améliorations, puis tout le reste en liste d'une ligne à la fin. Les montées de dépendances et les changements internes restent, car la seule personne qui les cherche en a vraiment besoin.

En Markdown, c'est un titre H2, une ligne atténuée avec version et date, puis des sections H3 pour Changements importants, Nouveautés, Améliorations et Corrections. Dans un email, c'est le même ordre avec le titre en objet. Dans un widget de changelog, ce sont le titre et le premier paragraphe, le reste derrière un lien. Le modèle ci-dessus, c'est cette forme écrite en détail.

Pour la rédaction elle-même, plus que pour la forme, voir Comment écrire des release notes que les gens lisent et Bonnes pratiques des release notes qui comptent sur le blog.

Questions fréquentes

Quelle devrait être la longueur des release notes ?

Aussi longues que les changements qui touchent les utilisateurs, et pas une ligne de plus. Une version avec une correction de bug mérite deux lignes. Gonfler une petite version pour la faire paraître importante habitue les gens à survoler les grandes.

Quelle est la différence entre release notes et changelog ?

En pratique, les termes sont utilisés indifféremment. Quand les équipes les distinguent, les release notes décrivent une seule version et s'adressent aux utilisateurs, tandis qu'un changelog est la liste continue de toutes les versions dans le temps. Ce modèle couvre une version ; un changelog, c'est ce qu'on obtient en les empilant, la plus récente en premier.

Les release notes doivent-elles avoir un numéro de version ?

Seulement si tes utilisateurs peuvent le voir. Les numéros de version sont utiles pour les API, les bibliothèques et les logiciels installés, où quelqu'un doit savoir sur quelle version il se trouve. Pour une application web à déploiement continu, la date est plus utile, car c'est ce que l'utilisateur peut comparer à ce qu'il a vécu.

Qui devrait les écrire ?

Celui qui sait ce qui a changé, ce qui est généralement la personne qui l'a fusionné, relu par celui qui tient le ton. La façon dont ça tourne mal, en les confiant entièrement à quelqu'un d'extérieur au travail, ce sont des notes qui décrivent le ticket au lieu du changement.