Qui écrit le changelog, et qui devrait l'écrire

Demandez à une équipe qui écrit le changelog et la réponse honnête est généralement « qui s’en souvient », ce qui est le même mode d’échec qu’imposer une entrée de changelog en CI existe pour corriger au niveau mécanique. Mais forcer l’existence d’une entrée ne décide pas qui est qualifiée pour bien l’écrire, et les équipes qui sautent cette question ont tendance à se rabattre par défaut sur qui est le plus facile à contraindre, généralement l’autrice de la PR, sans vérifier si c’est vraiment la personne qui peut bien l’écrire.

Pourquoi l’autrice de la PR n’est-elle pas automatiquement la meilleure rédactrice de changelog ?

Parce qu’elle connaît l’implémentation, pas nécessairement l’impact, et ce sont deux types de connaissance différents. Où s’arrêtent les conventional commits couvre cet écart côté message de commit : fix(auth): reject expired refresh tokens est correct et ne dit rien à une cliente, et qui a écrit ce correctif est souvent la personne la moins équipée pour le traduire, parce qu’elle a pensé en termes du bug pendant des heures et a perdu la vue extérieure de ce qu’une utilisatrice a réellement vécu. C’est la même raison pour laquelle les rédactrices techniques existent en tant que profession : traduire l’implémentation en impact est une compétence distincte du fait d’avoir construit la chose, et ça demande de la pratique, peu importe la qualité de la développeuse sur le code lui-même.

Cela signifie-t-il que le produit ou le support devraient écrire chaque entrée à la place ?

Non, parce qu’ils ont l’écart inverse : ils savent ce qui compte pour les utilisatrices mais pas toujours ce qui a vraiment été livré, ce qui produit des entrées lisibles mais occasionnellement fausses sur la portée, une affirmation « supporte maintenant X » pour une fonctionnalité encore derrière un flag, ou un correctif décrit comme complet alors qu’il ne couvre qu’un cas sur trois. Le mode d’échec des entrées écrites par des développeuses est illisible-mais-précis ; le mode d’échec des entrées écrites par des PM est lisible-mais-non-vérifié. Aucun rôle ne possède les deux moitiés de ce dont une bonne entrée a besoin.

À quoi ressemble vraiment un modèle de propriété qui fonctionne ?

Un brouillon de qui est le plus proche du changement, revu par qui est le plus proche de l’utilisatrice, avec une personne nommée responsable de la formulation finale au lieu que tout le monde suppose que quelqu’un d’autre attrapera les problèmes. Le brouillon a davantage besoin d’exister et d’être précis que d’être bon ; une phrase brute écrite par une développeuse qui dit correctement ce qui a changé est un meilleur point de départ qu’une polie mais non vérifiée, parce que réécrire pour la clarté est plus facile que réécrire pour la justesse. L’étape de revue est où une PM ou responsable support lit le brouillon et pose la seule question qui attrape l’écart de lisibilité : est-ce que je comprendrais ça si je n’avais pas vu le code.

La même personne devrait-elle toujours être la responsable, ou est-ce que ça tourne ?

Nommée et stable bat tournante, au moins pour la validation finale. Une responsable tournante signifie que chaque entrée est revue par quelqu’un qui re-dérive les conventions de l’équipe à partir de zéro, ce qui est exactement comment la voix dérive d’entrée en entrée et une lectrice commence à remarquer que le changelog a été écrit par un comité. Une seule personne, ou un très petit groupe stable, accumule les jugements avec le temps, quand dire « amélioré » plutôt que nommer le chiffre spécifique, quand un correctif a besoin de sa propre entrée plutôt que d’être fondu dans un lot, et ce jugement vaut plus que distribuer le travail équitablement.

Brouillon (développeuse, depuis la PR) :
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revu (responsable du changelog, vérifié contre la vraie PR) :
"Corrigé : les exports triés par date pouvaient retourner
des résultats désordonnés au-delà de la première page.
Maintenant cohérent sur toutes les pages."

Une petite équipe a-t-elle besoin d’autant de processus pour une ligne de texte ?

Pas les rôles en tant que personnes séparées, mais les deux étapes comptent encore même en solo. Une équipe d’une personne est à la fois la développeuse et la revieweuse, et la discipline qui survit à cette échelle est de faire la revue comme un passage mental séparé, pas de sauter directement de l’écriture du correctif à la publication d’une description de celui-ci dans le même souffle. Le piège à petite échelle, c’est de sauter entièrement le deuxième passage, pas le manque d’une deuxième personne, parce que personne d’externe ne l’impose, et l’écart de précision que ce passage existe pour attraper ne disparaît pas juste parce que la même personne pourrait théoriquement remarquer son propre angle mort.

Que se passe-t-il quand personne n’est responsable de l’entrée finale ?

Le changelog se dégrade de façon inégale plutôt que d’échouer carrément, ce qui est pire parce que personne ne le remarque jusqu’à ce qu’une lectrice le signale. Certaines entrées restent nettes parce que qui les a écrites s’en souciait ; d’autres deviennent vagues, « diverses améliorations et corrections de bugs », parce que qui les a écrites allait vite et que personne ne l’a attrapé avant publication. Les contraintes de format de Keep a Changelog attrapent la dérive structurelle, dates manquantes, mauvaises catégories, mais rien dans un modèle n’attrape une entrée vague qui est techniquement bien formatée, ce qui est exactement l’écart qu’une responsable nommée est là pour combler.

FAQ

La responsable du changelog devrait-elle être un rôle d’ingénierie ou de produit ? Les deux peuvent fonctionner si la personne a à la fois la fluidité technique pour vérifier la portée et assez de distance avec l’implémentation pour écrire pour une lectrice externe ; le titre compte moins que si elle peut faire les deux moitiés, ou sait à qui demander pour la moitié qu’elle ne peut pas.

Un planning tournant de type astreinte est-il jamais approprié pour la propriété du changelog ? Pour le volume, parfois, si l’équipe est trop petite pour qu’une personne revoie tout ; pour la voix et le jugement, non, parce que c’est exactement ce que la rotation érode. Une rotation qui partage la charge de rédaction tout en gardant une revieweuse stable obtient le bénéfice sans la dérive.

Quel est le signe le plus rapide que quelque chose ne va pas avec la configuration actuelle de propriété ? Des entrées précises mais illisibles, ou lisibles mais fausses sur la portée, selon un schéma qui suit qui les a écrites. Si la qualité corrèle avec l’autrice au lieu de rester cohérente, c’est la propriété qui est l’écart, pas la compétence rédactionnelle.

L’automatisation réduit-elle à quel point la propriété compte ? Elle réduit combien d’écriture est nécessaire, pas combien de jugement est nécessaire. L’automatisation du changelog couvre ce qu’un pipeline peut générer en sécurité, formatage, publication, cross-posting ; la formulation, le regroupement et ce qui compte comme digne de mention restent des décisions humaines peu importe combien du pipeline est automatisé.

Que faire si l’autrice de la PR et la revieweuse ne sont pas d’accord sur la formulation ? C’est à la revieweuse de trancher, parce que la question à laquelle elle répond, une lectrice extérieure comprendrait-elle ceci, est celle que le rôle existe pour protéger. Ça ne rend pas l’avis de la développeuse sans valeur : si le désaccord porte sur la justesse plutôt que sur la formulation, la revieweuse s’efface, parce que la portée est la moitié qui revient à l’autrice de bien cadrer. Séparer les deux types de désaccord, formulation contre justesse, évite que la plupart d’entre eux ne tournent à l’impasse.

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 : Comparatif d'outils de changelog, Générateur de changelog