Release notes de correctifs : écrire des entrées utiles

De bonnes release notes de correctifs décrivent ce que l’utilisateur a vu mal tourner, pas ce que le code a mal fait. Chaque entrée dit qui était concerné, depuis quand, si la correction est complète et si le lecteur doit faire quelque chose, même si c’est seulement “aucune action requise”.

La plupart des équipes recopient une ligne du message de commit. Le tableau montre six réécritures, et les sections qui suivent expliquent les règles.

Comment rédiger une entrée de correctif dans des release notes ?

Commencez par le symptôme dans les mots de l’utilisateur, puis qui était touché et depuis quand, puis l’état de la correction, puis l’action. Une ou deux phrases suffisent d’ordinaire. La cause dans le code a sa place dans la pull request, là où un ingénieur ira la chercher.

Un lecteur cherche une seule chose : “est-ce que c’était moi ?” Quatre éléments couvrent presque toutes les entrées :

1. Le symptôme. Ce qui est apparu à l’écran, dans la réponse de l’API ou sur la facture. Citez le texte de l’erreur s’il y en avait un, car les gens le recherchent.
2. La portée. Quel plan, quelle plateforme, quelle version d’API ou forme de données. “Les comptes de plus de 50 000 lignes” se vérifie. “Certains utilisateurs” non.
3. La période. Depuis quelle version ou quelle date, pour qu’un lecteur puisse décider si le résultat bizarre d’hier était ce bug.
4. L’action. Relancer, resynchroniser, mettre à jour, retirer un contournement, ou rien du tout.

Si des utilisateurs ont mis en place un contournement, c’est la ligne d’action qui leur dit qu’ils peuvent le supprimer.

Quelle différence entre une release note et un changelog ?

Un changelog est le registre complet et continu des changements. Les release notes sont un message choisi et réécrit sur une version, pour des gens qui se demandent si cela les concerne. Pour les correctifs, le changelog liste chaque correction et les notes mettent en tête celles qu’un lecteur pouvait remarquer.

Une coquille dans une infobulle va seulement dans le changelog. Un mauvais taux de TVA sur les factures va dans les deux. La répartition complète est dans changelog vs release notes, et la forme d’un bon ensemble de notes dans comment écrire des release notes.

Keep a Changelog est une convention pratique pour le côté registre. Elle réserve “Fixed” aux corrections de bugs et une rubrique “Security” séparée aux vulnérabilités, soit la même séparation que fait cet article pour le lecteur.

Un correctif est-il une mise à jour ?

Oui. Un correctif modifie le produit, donc en livrer un est une mise à jour. Avec le versionnage sémantique, un correctif rétrocompatible est une version patch, par exemple de 4.2.0 à 4.2.1.

Savoir si le lecteur doit faire quelque chose est une autre question, et la note doit y répondre. Un correctif qui change ce qu’observe un appelant correct est proche d’un changement cassant, et les changements cassants expliquent où se situe cette limite.

Quand un correctif mérite-t-il sa propre entrée, et quand est-il mineur ?

Donnez à un correctif sa propre entrée quand un utilisateur pouvait remarquer le bug, y perdre du temps ou des données, ou bâtir un contournement autour. Regroupez-le dans une courte liste “Corrections mineures” quand personne hors de votre équipe ne pouvait le voir. Jugez selon l’expérience du lecteur, quelle que soit la taille du diff.

Chaque ligne du groupe doit quand même dire quelque chose : “Corrections de quelques problèmes d’interface” est un texte de remplissage.

Comment parler d’une régression ?

Nommez la version qui l’a introduite, appelez cela une régression et donnez la version qui la corrige. Ceux qui ont subi le bug savent déjà que ça ne marchait pas, donc un aveu court et direct les sert mieux qu’une formulation vague.

Par exemple : “Les résultats de recherche pour les requêtes contenant un tiret revenaient vides en 4.1.0. C’est corrigé en 4.1.1. Si vous aviez modifié vos requêtes pour éviter les tirets, vous pouvez revenir en arrière.”

“Fiabilité de la recherche améliorée” passe pour de l’évasion aux yeux de quiconque a perdu un après-midi à cause du bug. Si la cause reste à confirmer, dites-le, comme le formulent les conseils sur les release notes d’urgence : ne laissez jamais la note paraître plus certaine que l’équipe.

Comment annoncer un correctif de sécurité ?

Indiquez la gravité sans détour, nommez les versions touchées et la version qui corrige, dites l’urgence de la mise à jour et incluez l’identifiant CVE s’il en existe un. Ne publiez les détails que lorsque les utilisateurs peuvent agir sur un correctif, en suivant un processus de divulgation coordonnée quand un rapporteur est impliqué.

L’ordre compte : le rapporteur vous prévient en privé, vous livrez le correctif, et la note publique sort quand les utilisateurs peuvent se protéger. Le processus de divulgation coordonnée des vulnérabilités de la CISA coordonne le signalement, l’analyse et la divulgation publique des vulnérabilités. Les règles des CVE Numbering Authorities régissent l’attribution et la publication des enregistrements CVE, et sur GitHub un repository security advisory permet de rédiger l’avis en privé et de demander un identifiant.

Une entrée de sécurité porte en général quatre faits :

• Ce qu’un attaquant pouvait faire, en une phrase et sans preuve de concept.
• Les versions touchées, et la version qui corrige.
• L’urgence : “mettez à jour aujourd’hui” ou “mettez à jour à votre prochaine version”.
• Si vous avez observé une exploitation, et un crédit au rapporteur s’il est d’accord.

Laissez de côté les étapes d’exploitation.

Que doit dire une note sur la correction d’une perte de données ?

Dites quelles données étaient touchées, comment savoir si les vôtres l’étaient et si on peut les récupérer. “Aucune action requise” est rarement vrai ici, et la première question du lecteur est “mes données sont-elles perdues”.

Une entrée utilisable donne la condition qui faisait perdre des données (“supprimer un dossier pendant une synchronisation”), la période où c’était possible, un moyen de vérifier (“ouvrez la Corbeille et cherchez les éléments datés du 3 au 9 septembre”) et le chemin de récupération. Si les données ne peuvent pas être récupérées, dites-le. Contactez aussi directement les clients touchés, car la release note ne doit pas être le seul endroit où quelqu’un apprend que ses données ont été touchées.

Pourquoi “Corrections de bugs et améliorations de performance” est-il une mauvaise note ?

Cela ne donne rien à faire au lecteur et cache les corrections que quelqu’un attendait. Un client qui avait signalé un plantage ne peut pas savoir s’il est corrigé, et un client qui a un contournement ne peut pas savoir s’il doit le retirer.

Il y a deux alternatives honnêtes. Si une version n’a rien qu’un lecteur pourrait remarquer, ne publiez pas de notes pour elle et laissez le changelog garder la trace. Si elle a des corrections, listez-les dans les termes du lecteur :

Avant :
  Corrections de bugs et améliorations de performance.

Après :
  Corrigé : l'export CSV échouait pour les projets sans tags.
  Corrigé : le mode sombre cachait le curseur dans les commentaires.
  Plus rapide : le tableau de bord s'ouvre plus vite pour les
  espaces de plus de 100 projets.

D’où viennent les notes de correctifs ?

Elles viennent de la pull request qui a corrigé le bug et du signalement qui l’a déclenchée. Si les mots de la personne qui a signalé le problème accompagnent le correctif, la moitié du symptôme est déjà écrite.

Demande de fonctionnalité ou bug explique pourquoi étiqueter correctement un signalement décide de qui en est responsable. Dans Changeloop, un bug signalé via le widget devient une issue GitHub étiquetée bug, et l’entrée de changelog est rédigée à partir de la pull request fusionnée puis retenue jusqu’à l’approbation d’une personne avant publication. Le modèle de release notes vous donne la même forme d’entrée pour écrire à la main : symptôme, portée, période, action.

FAQ

Que doivent contenir les release notes de correctifs ? Chaque entrée doit nommer le symptôme vu par l’utilisateur, qui était touché, depuis quelle version ou quelle date, si la correction est complète et ce que le lecteur doit faire, y compris “rien”.

Faut-il lister chaque correctif dans les release notes ? Non. Listez ceux qu’un utilisateur pouvait remarquer, qui lui ont fait perdre du temps ou qu’il a contournés, et regroupez les corrections cosmétiques ou internes dans une courte liste “Corrections mineures”. Le changelog garde chaque correction pour qui doit en retrouver une.

Comment rédiger des release notes pour un bug que vous avez introduit ? Dites que c’était une régression, nommez la version qui l’a introduite et celle qui la corrige, et indiquez aux lecteurs s’ils peuvent retirer un contournement. Une formulation directe se lit mieux qu’une formulation adoucie.

Comment consulter les release notes d’un produit que vous utilisez ? Cherchez une page changelog ou release notes liée depuis le menu d’aide, le pied de page ou la documentation du produit, ou l’onglet des releases du dépôt pour les projets open source.

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.

À voir sur changeloop : Modèle de release notes