Changelog-automatisering, en haar grenzen

Changelog-automatisering werkt wanneer die verzameling, classificatie en publicatie automatiseert, en stopt bij selectie en formulering. Automatiseer alles en je levert een geformatteerde git log; automatiseer niets en de changelog wordt in vlagen geschreven, uit het geheugen, vlak voor releases. De nuttige vraag is welke delen te automatiseren, niet hoeveel.

Changelog-automatiseringsprojecten falen in één van twee richtingen, en beide zijn voorspelbaar vanaf de eerste ontwerpvergadering. Automatiseer te weinig en de changelog is een document dat iemand geacht wordt bij te werken, wat betekent dat het in vlagen wordt bijgewerkt, door wie de korte lucifer trok. Automatiseer te veel en het wordt een geformatteerde git log: compleet, accuraat, en door niemand gelezen.

Welke delen van een changelog zouden geautomatiseerd moeten worden?

Drie van de vier stappen. Verzameling en publicatie volledig; classificatie als eerste doorgang met menselijke override; selectie en formulering nooit.

Verzameling. Veranderingen uit de plek halen waar ze gebeuren (commits, PR’s, tickets) en in een lijst zetten. Automatiseer dit volledig. Mensen zijn er slecht in, het is vervelend, en het is de stap die onder deadline wordt overgeslagen. Conventional commits of PR-labels zijn het gebruikelijke ruwe materiaal.

Classificatie. Beslissen of iets Added, Fixed, Changed, Deprecated, Removed of Security is. Automatiseer de eerste doorgang uit het commit-type of PR-label, en laat een mens overriden. De nauwkeurigheid hier ligt rond de tachtig procent puur uit metadata, en de foute twintig procent concentreert zich precies op de entries die ertoe doen, omdat dubbelzinnigheid correleert met belang.

Selectie en formulering. Beslissen wat een lezer verteld moet worden en hoe het te zeggen. Automatiseer dit niet. Het is de hele waarde van het artefact. Al het andere is logistiek.

Publicatie. De afgeronde entries naar een pagina, een feed, een e-mail, een in-app-widget, een Slack-kanaal brengen. Automatiseer volledig, en vanuit één bron. Hier gaat het meeste handmatige werk daadwerkelijk naartoe, en bijna niemand telt het. Het is ook de stap die de persoon die om de verandering vroeg kan vertellen dat die is uitgebracht, wat het hele onderwerp is van de feedback-loop sluiten vanuit de changelog. De e-mailhelft van die stap heeft zijn eigen vorm, in de product-update e-mailtemplate.

Dat laatste punt is het waard om bij stil te staan. Teams neigen ertoe de changelog te zien als een schrijfprobleem, en besteden dan de meeste tijd aan distributie: entries kopiëren naar een e-mailtool, herformatteren voor in-app, plakken in Slack, een docspagina bijwerken. Het schrijven kost een uur. Het kopiëren kost een uur per release, voor altijd, en dat is het deel dat een machine zou moeten hebben.

Wat gebeurt er als de grens verschuift?

Verschuif hem omhoog en je krijgt een git-dump. Volledige automatisering uit commits levert bump deps, fix flaky test, wip en address review comments voor klanten. Elk team dat dit heeft gedaan heeft daarna een filter toegevoegd, en het filter is een selectiestap die onder een andere naam opnieuw wordt geïntroduceerd, met slechtere ergonomie.

Verschuif hem omlaag en je krijgt vlagen. Volledig handmatige verzameling betekent dat entries op releasemoment uit het geheugen worden geschreven. Dat is de modus waar Keep a Changelog meteen al voor waarschuwt, en het verslechtert stilletjes: de changelog lijkt onderhouden tot precies de week dat niemand tijd had.

Hoe ziet een changelog-automatiseringspipeline eruit?

Vier stappen, met precies één menselijke poort, geplaatst waar een concept publiek wordt.

1. Leid bij het mergen een conceptentry af uit de PR: type uit label of commit-prefix, titel als eerste concept, link terug naar de PR, auteur vastgelegd. Zet het in een unreleased-bak.
2. Iedereen kan elk concept op elk moment bewerken, en bewerken is goedkoop. De meeste krijgen één regel herschreven.
3. Een release snijden vereist dat elke entry in de bak of bewerkt of expliciet als intern gemarkeerd is. Deze poort is het hele ontwerp. Zonder haar worden concepten ongewijzigd uitgebracht in de drukke week.
4. Publiceren is een fan-out vanuit de uitgebrachte set: de publieke pagina, de feed, de e-mail, de widget, de Slack-post. Eén bron, meerdere weergaven, geen kopiëren.

Stap 3 is de enige plek waar een mens nodig is, en het duurt ongeveer tien minuten per release zodra de concepten fatsoenlijk zijn. Waar een klantverzoek bij betrokken is, draagt het concept ook de issue die het sluit, wat is wat stap 4 in staat stelt de aanvrager te informeren; de feature-request-template is zo ontworpen dat die link overleeft. Waar deze stap in de bredere releaseflow zit, is het onderwerp van het releasemanagementproces.

Wat vereist automatisering van jullie data?

Niets van het bovenstaande werkt als de changelog een Markdown-bestand is, want een bestand kan niet naar vijf oppervlakken worden weergegeven zonder opnieuw te worden geparset, en proza parsen is hoe je eindigt met een widget die de helft van een kop toont.

Entries moeten gestructureerd zijn: een type, een datum, een versie of release-identifier, een doelgroep, een body en een link. Dan zijn het bestand, de pagina, de feed en de e-mail allemaal weergaven. Dat structurele punt is het enige wat de moeite waard is om goed te doen voordat je een tool kiest, omdat het is wat je niet goedkoop kunt naboren. Niets daarvan werkt zolang er niet echt een item wordt gemaakt voor elke wijziging die het nodig heeft; een changelog-item afdwingen in CI behandelt hoe je de pipeline een merge zonder item laat weigeren, in plaats van die stap aan het geheugen over te laten.

Wij bouwen changeloop, waar de changelog eerst een feed is en dan pas een pagina, dus lees dit als een belang in plaats van een onpartijdige aanbeveling; de prijzen zijn één gratis repository zonder kaart, genoeg om de vorm te zien. Changelog-tools is ons overzicht van wat er verder is, inclusief de producten waarmee we concurreren, en de changelog-generator doet de verzamelings- en classificatiestappen in de browser als je de afleiding wilt zien voordat je je aan een pipeline verbindt.

De test

Tel de minuten tussen een gemergede verandering en die verandering zichtbaar voor een klant die jullie repo niet leest. Als de meeste van die minuten iemand is die tekst tussen tools kopieert, is de automatisering die jullie nodig hebben in de publicatie, niet in het schrijven.

FAQ

Kan AI de changelog schrijven? Die kan er een opstellen. Een model dat de gemergede pull request krijgt levert meestal een bruikbaar eerste concept van titel en body op, wat de verzamelings- en classificatiestappen beter gedaan is. De selectie, of een lezer überhaupt iets verteld moet worden, en de uiteindelijke formulering hebben nog steeds de persoon nodig die de doelgroep kent, en een pipeline die concepten publiceert zonder die poort heeft de verkeerde stap geautomatiseerd.

Wat is het verschil tussen een changelog-generator en changelog-automatisering? Een generator zet commits eenmalig, op verzoek, om in een geformatteerde lijst. Automatisering draait bij elke merge, houdt een unreleased-bak bij, laat de release afhangen van menselijke review, en publiceert naar elk oppervlak vanuit één bron. De generator is de eerste, met de hand uitgevoerde stap van de pipeline.

Zou de changelog geautomatiseerd moeten worden uit commits of uit pull requests? Uit pull requests, waar de eenheid van verandering de PR is: de titel en beschrijving worden eenmalig geschreven, voor de hele verandering, en de PR linkt de issue die het sluit. Commit-gebaseerde afleiding werkt wanneer de commit de eenheid is en een conventie volgt.

Hoe voorkom je dat automatisering interne veranderingen publiceert? Classificeer chore, ci, test, refactor en dependency-updates standaard als intern, en maak promotie naar publiek een bewuste handeling. De omgekeerde standaard, publiek tenzij iemand het verbergt, is hoe bump deps klanten bereikt.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Changelog-tools vergeleken, Changelog-generator