Automatizarea changelog-ului, și limitele sale

Automatizarea changelog-ului funcționează când automatizează colectarea, clasificarea și publicarea, și se oprește la selecție și formulare. Automatizați totul și livrați un jurnal git formatat; nu automatizați nimic și changelog-ul e scris în rafale, din memorie, înainte de versiuni. Întrebarea utilă e care părți să automatizați, nu cât de mult.

Proiectele de automatizare a changelog-ului eșuează într-una din două direcții, și ambele sunt previzibile încă din prima ședință de design. Automatizați prea puțin și changelog-ul devine un document pe care cineva ar trebui să-l actualizeze, ceea ce înseamnă că e actualizat în rafale, de oricine a tras paiul cel mai scurt. Automatizați prea mult și se transformă într-un jurnal git formatat: complet, precis, și necitit de nimeni.

Ce părți ale unui changelog ar trebui automatizate?

Trei din cei patru pași. Colectarea și publicarea complet; clasificarea ca o primă trecere cu suprascriere umană; selecția și formularea niciodată.

Colectare. Scoaterea schimbărilor din locul unde se întâmplă (commit-uri, PR-uri, tichete) și punerea lor într-o listă. Automatizați asta complet. Oamenii sunt slabi la asta, e plictisitor, și e pasul care e sărit sub presiunea termenului. Conventional commits sau etichetele PR sunt materia primă obișnuită.

Clasificare. Decizia dacă ceva e Added, Fixed, Changed, Deprecated, Removed sau Security. Automatizați prima trecere din tipul commit-ului sau eticheta PR, și lăsați o persoană să suprascrie. Acuratețea aici e în jur de optzeci la sută doar din metadate, iar cele douăzeci la sută greșite se concentrează exact pe intrările care contează, pentru că ambiguitatea corelează cu importanța.

Selecție și formulare. Decizia despre ce ar trebui să știe un cititor și cum să i se spună. Nu automatizați asta. E toată valoarea artefactului. Tot restul e logistică.

Publicare. Aducerea intrărilor finalizate pe o pagină, un flux, un e-mail, un widget in-app, un canal Slack. Automatizați complet, și dintr-o singură sursă. Aici merge de fapt majoritatea efortului manual, și aproape nimeni nu-l numără. E de asemenea pasul care poate spune persoanei care a cerut schimbarea că a fost lansată, ceea ce e tot subiectul închiderii buclei de feedback din partea changelog-ului. Jumătatea de e-mail a acelui pas are propria formă, în șablonul de e-mail de actualizare produs.

Ultimul punct merită gândit. Echipele tind să vadă changelog-ul ca o problemă de scriere, apoi petrec majoritatea timpului pe distribuție: copiind intrări într-o unealtă de e-mail, reformatându-le pentru in-app, lipindu-le în Slack, actualizând o pagină de documentație. Scrierea durează o oră. Copierea durează o oră la fiecare versiune, pentru totdeauna, și e partea pe care ar trebui s-o aibă o mașină.

Ce se întâmplă când linia se mută?

Mutați-o în sus și obțineți o deversare git. Automatizarea totală din commit-uri produce bump deps, fix flaky test, wip și address review comments în fața clienților. Fiecare echipă care a făcut asta a adăugat apoi un filtru, iar filtrul e un pas de selecție reintrodus sub alt nume, cu ergonomie mai proastă.

Mutați-o în jos și obțineți rafale. Colectarea complet manuală înseamnă că intrările sunt scrise din memorie la momentul lansării. Ăsta e modul împotriva căruia avertizează Keep a Changelog încă de la început, și se degradează liniștit: changelog-ul pare întreținut până exact în săptămâna în care nimeni n-a avut timp.

Cum arată un pipeline de automatizare a changelog-ului?

Patru pași, cu exact o poartă umană, plasată acolo unde o ciornă devine publică.

1. La merge, derivați o intrare ciornă din PR: tip din etichetă sau prefix de commit, titlu ca primă ciornă, link înapoi la PR, autoare înregistrată. Puneți-o într-un coș nelansat.
2. Oricine poate edita orice ciornă în orice moment, iar editarea e ieftină. Majoritatea primesc o linie rescrisă.
3. Tăierea unei versiuni cere ca fiecare intrare din coș să fie fie editată, fie marcată explicit ca internă. Această poartă e tot designul. Fără ea, ciornele sunt lansate needitate în săptămâna aglomerată.
4. Publicarea e o difuzare din setul lansat: pagina publică, fluxul, e-mailul, widget-ul, postarea Slack. O sursă, mai multe randări, fără copiere.

Pasul 3 e singurul loc unde e necesară o persoană, și durează cam zece minute pe versiune odată ce ciornele sunt decente. Acolo unde e implicată o cerere de client, ciorna poartă și issue-ul pe care-l închide, ceea ce permite pasului 4 să-l informeze pe cel care a cerut; șablonul de cerere de funcție e conceput ca acel link să supraviețuiască. Locul acestui pas în fluxul mai larg de lansare e subiectul articolului despre procesul de gestionare a lansărilor.

Ce cere automatizarea de la datele voastre?

Nimic din ce e mai sus nu funcționează dacă changelog-ul e un fișier Markdown, pentru că un fișier nu poate fi randat pe cinci suprafețe fără a fi re-parsat, iar analizarea prozei e cum ajungeți cu un widget care afișează jumătate de titlu.

Intrările trebuie să fie structurate: un tip, o dată, o versiune sau un identificator de lansare, o audiență, un corp și un link. Atunci fișierul, pagina, fluxul și e-mailul sunt toate vizualizări. Acel punct structural e singurul lucru care merită făcut bine înainte de a alege o unealtă, pentru că e ce nu puteți adăuga ieftin mai târziu. Nimic din asta nu funcționează dacă o intrare nu e chiar creată pentru fiecare schimbare care are nevoie de ea; impunerea unei intrări de changelog în CI acoperă cum să faceți pipeline-ul să refuze un merge fără intrare, în loc să lăsați acel pas pe seama memoriei.

Construim changeloop, unde changelog-ul e mai întâi un flux și apoi o pagină, deci citiți asta ca un interes, nu ca o recomandare imparțială; prețurile sunt un repository gratuit fără card, suficient să vedeți forma. Unelte pentru changelog e rezumatul nostru despre ce mai există, inclusiv produsele cu care concurăm, iar generatorul de changelog face pașii de colectare și clasificare în browser dacă vreți să vedeți derivarea înainte de a vă angaja într-un pipeline.

Testul

Numărați minutele dintre o schimbare integrată și acea schimbare vizibilă pentru o clientă care nu vă citește repo-ul. Dacă majoritatea acelor minute e cineva copiind text între unelte, automatizarea de care aveți nevoie e în publicare, nu în scriere.

FAQ

Poate AI-ul să scrie changelog-ul? Poate redacta unul. Un model căruia i se dă pull request-ul integrat produce de cele mai multe ori o primă ciornă utilizabilă a titlului și corpului, ceea ce e colectarea și clasificarea făcute mai bine. Selecția, dacă unui cititor ar trebui să i se spună ceva, și formularea finală, încă au nevoie de persoana care cunoaște audiența, iar un pipeline care publică ciorne fără acea poartă a automatizat pasul greșit.

Care e diferența dintre un generator de changelog și automatizarea changelog-ului? Un generator transformă commit-uri într-o listă formatată o dată, la cerere. Automatizarea rulează la fiecare merge, menține un coș nelansat, condiționează lansarea de revizuire umană, și publică pe fiecare suprafață dintr-o singură sursă. Generatorul e primul pas al pipeline-ului, rulat manual.

Ar trebui changelog-ul automatizat din commit-uri sau din pull request-uri? Din pull request-uri, unde unitatea de schimbare e PR-ul: titlul și descrierea sunt scrise o dată, pentru toată schimbarea, iar PR-ul leagă issue-ul pe care-l închide. Derivarea bazată pe commit-uri funcționează când commit-ul e unitatea și urmează o convenție.

Cum se previne ca automatizarea să publice schimbări interne? Clasificați chore, ci, test, refactor și actualizările de dependențe ca interne implicit, și faceți din promovarea la public un act deliberat. Valoarea implicită inversă, public dacă nimeni nu-l ascunde, e cum bump deps ajunge la clienți.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Comparație instrumente changelog, Generator de changelog