Automatisation du changelog, et ses limites

L’automatisation du changelog fonctionne quand elle automatise la collecte, la classification et la publication, et s’arrête à la sélection et à la formulation. Automatisez tout et vous livrez un git log formaté ; n’automatisez rien et le changelog est écrit par rafales, de mémoire, avant les versions. La question utile est quelles parties automatiser, pas combien.

Les projets d’automatisation de changelog échouent dans une de deux directions, et les deux sont prévisibles dès la première réunion de design. Automatisez trop peu et le changelog est un document que quelqu’un est censé mettre à jour, ce qui signifie qu’il est mis à jour par rafales, par quiconque a tiré la courte paille. Automatisez trop et ça devient un git log formaté : complet, précis, et lu par personne.

Quelles parties d’un changelog devraient être automatisées ?

Trois des quatre étapes. Collecte et publication complètement ; classification comme première passe avec dérogation humaine ; sélection et formulation jamais.

Collecte. Sortir les changements de l’endroit où ils se produisent (commits, PR, tickets) et les mettre dans une liste. Automatisez ça complètement. Les humains sont mauvais pour ça, c’est fastidieux, et c’est l’étape sautée sous délai. Conventional commits ou les labels de PR sont la matière première habituelle.

Classification. Décider si quelque chose est Added, Fixed, Changed, Deprecated, Removed ou Security. Automatisez la première passe depuis le type de commit ou le label de PR, et laissez un humain déroger. La précision ici tourne autour de quatre-vingts pour cent depuis les métadonnées seules, et les vingt pour cent faux se concentrent exactement sur les entrées qui comptent, parce que l’ambiguïté corrèle avec l’importance.

Sélection et formulation. Décider ce qu’un lecteur devrait savoir et comment le dire. N’automatisez pas ça. C’est toute la valeur de l’artefact. Tout le reste est de la logistique.

Publication. Amener les entrées finies vers une page, un flux, un email, un widget in-app, un canal Slack. Automatisez complètement, et depuis une source. C’est là que va la majorité de l’effort manuel réel, et presque personne ne le compte. C’est aussi l’étape qui peut dire à la personne qui a demandé le changement qu’il a été livré, ce qui est tout le sujet de fermer la boucle de feedback depuis le changelog. La moitié email de cette étape a sa propre forme, dans le modèle d’email de mise à jour produit.

Ce dernier point mérite qu’on s’y arrête. Les équipes tendent à voir le changelog comme un problème d’écriture, puis passent la majorité de leur temps sur la distribution : copier des entrées dans un outil email, reformater pour l’in-app, coller dans Slack, mettre à jour une page docs. L’écriture prend une heure. La copie prend une heure à chaque version, pour toujours, et c’est la partie qu’une machine devrait avoir.

Que se passe-t-il quand la ligne bouge ?

Déplacez-la vers le haut et vous obtenez un dump de git. L’automatisation totale depuis les commits produit bump deps, fix flaky test, wip et address review comments devant les clients. Chaque équipe qui a fait ça a ensuite ajouté un filtre, et le filtre est une étape de sélection réintroduite sous un autre nom, avec une pire ergonomie.

Déplacez-la vers le bas et vous obtenez des rafales. La collecte totalement manuelle signifie que les entrées sont écrites de mémoire au moment de la version. C’est le mode contre lequel Keep a Changelog avertit dès le début, et ça se dégrade silencieusement : le changelog paraît entretenu jusqu’à la semaine où personne n’a eu le temps.

À quoi ressemble un pipeline d’automatisation de changelog ?

Quatre étapes, avec exactement une porte humaine, placée là où un brouillon devient public.

1. Au merge, dérivez une entrée brouillon de la PR : type depuis le label ou le préfixe de commit, titre comme premier brouillon, lien retour vers la PR, autrice enregistrée. Faites-la atterrir dans un bac non publié.
2. N’importe qui peut éditer n’importe quel brouillon à n’importe quel moment, et éditer est bon marché. La plupart reçoivent une ligne réécrite.
3. Tailler une version exige que chaque entrée du bac soit soit éditée soit explicitement marquée interne. Cette porte est tout le design. Sans elle, les brouillons sont livrés non édités la semaine chargée.
4. Publier est un fan-out depuis l’ensemble publié : la page publique, le flux, l’email, le widget, le post Slack. Une source, plusieurs rendus, pas de copie.

L’étape 3 est le seul endroit où une personne est requise, et elle prend environ dix minutes par version une fois que les brouillons sont corrects. Là où une demande de cliente est impliquée, le brouillon porte aussi l’issue qu’il ferme, ce qui est ce qui permet à l’étape 4 d’avertir la demandeuse ; la template de demande de fonctionnalité est conçue pour que ce lien survive. La place de cette étape dans le flux de release plus large fait l’objet du processus de release management.

Que demande l’automatisation à vos données ?

Rien de tout ça ne fonctionne si le changelog est un fichier Markdown, parce qu’un fichier ne peut pas être rendu sur cinq surfaces sans être reparsé, et parser de la prose est comment on finit avec un widget qui affiche la moitié d’un titre.

Les entrées doivent être structurées : un type, une date, une version ou identifiant de release, une audience, un corps et un lien. Alors le fichier, la page, le flux et l’email sont tous des vues. Ce point structurel est la seule chose qui vaut la peine d’être bien faite avant de choisir un outil, parce que c’est ce qu’on ne peut pas rajouter après bon marché. Rien de tout ça ne fonctionne si une entrée n’est pas vraiment créée pour chaque changement qui en a besoin ; exiger une entrée de changelog en CI couvre comment faire refuser un merge sans entrée par le pipeline, au lieu de laisser cette étape à la mémoire.

On construit changeloop, où le changelog est d’abord un flux puis une page, donc lisez ça comme un intérêt plutôt qu’une recommandation impartiale ; le pricing est un repository gratuit sans carte, suffisant pour voir la forme. Outils de changelog est notre récap de ce qui existe d’autre, y compris les produits avec lesquels on est en concurrence, et le générateur de changelog fait les étapes de collecte et classification dans le navigateur si vous voulez voir la dérivation avant de vous engager dans un pipeline.

Le test

Comptez les minutes entre un changement mergé et ce changement visible pour une cliente qui ne lit pas votre repo. Si la plupart de ces minutes, c’est quelqu’un qui copie du texte entre outils, l’automatisation dont vous avez besoin est dans la publication, pas dans l’écriture.

FAQ

L’IA peut-elle écrire le changelog ? Elle peut en rédiger un brouillon. Un modèle à qui on donne la pull request mergée produit la plupart du temps un premier brouillon utilisable du titre et du corps, ce qui est la collecte et la classification mieux faites. La sélection, si dire quelque chose à un lecteur, et la formulation finale, ont toujours besoin de la personne qui connaît l’audience, et un pipeline qui publie des brouillons sans cette porte a automatisé la mauvaise étape.

Quelle est la différence entre un générateur de changelog et l’automatisation du changelog ? Un générateur transforme des commits en une liste formatée une fois, à la demande. L’automatisation tourne à chaque merge, maintient un bac non publié, conditionne la version à une revue humaine, et publie sur chaque surface depuis une source. Le générateur est la première étape du pipeline, exécutée à la main.

Le changelog devrait-il être automatisé depuis les commits ou les pull requests ? Depuis les pull requests, où l’unité de changement est la PR : le titre et la description sont écrits une fois, pour tout le changement, et la PR lie l’issue qu’elle ferme. La dérivation basée sur les commits fonctionne quand le commit est l’unité et suit une convention.

Comment empêche-t-on l’automatisation de publier des changements internes ? Classifiez chore, ci, test, refactor et les mises à jour de dépendances comme internes par défaut, et faites de la promotion vers public un acte délibéré. Le défaut inverse, public sauf si quelqu’un le cache, est comment bump deps atteint les clients.

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