Automatizace changelogu, a její limity

Automatizace changelogu funguje, když automatizuje sběr, klasifikaci a zveřejňování, a zastavuje se u výběru a formulace. Automatizujte vše a dodáte naformátovaný git log; neautomatizujte nic a changelog se píše v nárazech, z paměti, před vydáními. Užitečná otázka je, které části automatizovat, ne kolik.

Projekty automatizace changelogu selhávají v jednom ze dvou směrů, a oba jsou předvídatelné už od první schůzky o designu. Automatizujte příliš málo a changelog se stane dokumentem, který by měl někdo aktualizovat, což znamená, že je aktualizován v nárazech, kýmkoli, kdo vytáhl kratší slámku. Automatizujte příliš mnoho a promění se v naformátovaný git log: úplný, přesný, a nikým nečtený.

Které části changelogu by měly být automatizované?

Tři ze čtyř kroků. Sběr a zveřejňování zcela; klasifikace jako první průchod s lidským přepsáním; výběr a formulace nikdy.

Sběr. Vytažení změn z místa, kde se dějí (commity, PR, tickety), a jejich vložení do seznamu. Automatizujte to zcela. Lidé jsou v tom špatní, je to únavné, a je to krok, který se přeskakuje pod termínem. Conventional commits nebo štítky PR jsou obvyklá surovina.

Klasifikace. Rozhodnutí, zda je něco Added, Fixed, Changed, Deprecated, Removed nebo Security. Automatizujte první průchod z typu commitu nebo štítku PR, a nechte člověka přepsat. Přesnost je zde kolem osmdesáti procent jen z metadat, a chybných dvacet procent se soustředí přesně na záznamy, na kterých záleží, protože nejednoznačnost koreluje s významností.

Výběr a formulace. Rozhodnutí o tom, co by měl čtenář vědět a jak to říct. Neautomatizujte to. To je celá hodnota artefaktu. Vše ostatní je logistika.

Zveřejnění. Dopravení hotových záznamů na stránku, do kanálu, e-mailu, in-app widgetu, Slack kanálu. Automatizujte zcela, a z jednoho zdroje. Sem skutečně jde většina ručního úsilí, a téměř nikdo to nepočítá. Je to také krok, který může sdělit osobě, jež o změnu požádala, že byla vydána, což je celý obsah uzavírání smyčky zpětné vazby ze strany changelogu. E-mailová polovina tohoto kroku má vlastní podobu, v šabloně e-mailu o aktualizaci produktu.

Poslední bod stojí za zamyšlení. Týmy mají tendenci vidět changelog jako problém psaní, a pak tráví většinu času distribucí: kopírováním záznamů do e-mailového nástroje, přeformátováním pro in-app, vkládáním do Slacku, aktualizací stránky dokumentace. Psaní trvá hodinu. Kopírování trvá hodinu při každém vydání, navždy, a je to část, kterou by měl mít stroj.

Co se stane, když se hranice posune?

Posuňte ji nahoru a dostanete výpis git. Plná automatizace z commitů produkuje bump deps, fix flaky test, wip a address review comments před zákazníky. Každý tým, který to udělal, pak přidal filtr, a filtr je krok výběru znovu zavedený pod jiným jménem, s horší ergonomií.

Posuňte ji dolů a dostanete nárazy. Zcela ruční sběr znamená, že záznamy se píší z paměti v okamžiku vydání. Toto je režim, před kterým Keep a Changelog varuje hned na začátku, a tiše se zhoršuje: changelog vypadá udržovaně až do přesně toho týdne, kdy nikdo neměl čas.

Jak vypadá pipeline automatizace changelogu?

Čtyři kroky, s přesně jednou lidskou branou, umístěnou tam, kde se koncept stává veřejným.

1. Při merge odvoďte konceptový záznam z PR: typ ze štítku nebo prefixu commitu, titulek jako první koncept, odkaz zpět na PR, zaznamenaná autorka. Umístěte ho do nevydaného koše.
2. Kdokoli může kdykoli upravit jakýkoli koncept, a úprava je levná. Většina dostane přepsaný jeden řádek.
3. Vystřižení vydání vyžaduje, aby každý záznam v koši byl buď upraven, nebo výslovně označen jako interní. Tato brána je celý design. Bez ní se koncepty vydávají neupravené v rušném týdnu.
4. Zveřejnění je rozvětvení z vydané sady: veřejná stránka, kanál, e-mail, widget, příspěvek na Slacku. Jeden zdroj, více vykreslení, žádné kopírování.

Krok 3 je jediné místo, kde je potřeba člověk, a trvá asi deset minut na vydání, jakmile jsou koncepty slušné. Tam, kde je zapojen požadavek zákazníka, koncept také nese issue, které uzavírá, což umožňuje kroku 4 informovat žadatele; šablona požadavku na funkci je navržena tak, aby tento odkaz přežil. Kam tento krok zapadá v širším toku vydání, je tématem článku proces správy vydání.

Co automatizace vyžaduje od vašich dat?

Nic z výše uvedeného nefunguje, pokud je changelog soubor Markdown, protože soubor nelze vykreslit na pěti povrchách bez opětovného parsování, a parsování prózy je způsob, jak skončíte s widgetem, který zobrazuje polovinu titulku.

Záznamy musí být strukturované: typ, datum, verze nebo identifikátor vydání, publikum, tělo a odkaz. Pak jsou soubor, stránka, kanál a e-mail všechny pohledy. Tento strukturální bod je jediná věc, kterou stojí za to udělat správně před výběrem nástroje, protože je to to, co nemůžete levně dodat později. Nic z tohohle nefunguje, pokud se pro každou změnu, která to potřebuje, doopravdy nevytvoří záznam; vynucení záznamu changelogu v CI pokrývá, jak donutit pipeline odmítnout merge bez záznamu, místo aby ten krok nechala na paměti.

Stavíme changeloop, kde je changelog nejprve kanál a teprve pak stránka, takže to čtěte jako zájem, ne nestranné doporučení; ceník je jeden bezplatný repozitář bez karty, dostatečný, aby ukázal tvar. Nástroje pro changelog je náš přehled toho, co ještě existuje, včetně produktů, se kterými soupeříme, a generátor changelogu provádí kroky sběru a klasifikace v prohlížeči, pokud chcete vidět odvození, než se zavážete k pipeline.

Test

Spočítejte minuty mezi sloučenou změnou a viditelností té změny pro zákaznici, která nečte váš repo. Pokud je většina těch minut někdo kopírující text mezi nástroji, automatizace, kterou potřebujete, je ve zveřejnění, ne v psaní.

FAQ

Může AI napsat changelog? Může sestavit koncept. Model, kterému je dán sloučený pull request, nejčastěji produkuje použitelný první koncept titulku a těla, což je sběr a klasifikace udělané lépe. Výběr, zda by se čtenáři vůbec mělo něco říct, a finální formulace, stále potřebují osobu, která zná publikum, a pipeline, který zveřejňuje koncepty bez této brány, automatizoval špatný krok.

Jaký je rozdíl mezi generátorem changelogu a automatizací changelogu? Generátor promění commity v naformátovaný seznam jednou, na požádání. Automatizace běží při každém merge, udržuje nevydaný koš, podmiňuje vydání lidskou revizí, a zveřejňuje na každý povrch z jednoho zdroje. Generátor je první krok pipeline, prováděný ručně.

Měl by být changelog automatizován z commitů nebo z pull requestů? Z pull requestů, kde jednotkou změny je PR: titulek a popis se píší jednou, pro celou změnu, a PR propojuje issue, které uzavírá. Odvození založené na commitech funguje, když je commit jednotkou a řídí se konvencí.

Jak se zabrání tomu, aby automatizace zveřejnila interní změny? Klasifikujte chore, ci, test, refactor a aktualizace závislostí jako interní ve výchozím nastavení, a udělejte z povýšení na veřejné vědomý akt. Opačné výchozí nastavení, veřejné pokud to někdo neskryje, je způsob, jak se bump deps dostane k zákazníkům.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Srovnání nástrojů pro changelog, Generátor changelogu