Automatizace changelogu: co automatizovat a co ne
6 min čtení aktualizováno
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.
| Krok | Automatizovat? | Proč |
|---|---|---|
| Sběr: změny z commitů, PR, ticketů do seznamu | Zcela | Únavné, přeskakuje se pod termínem, stroje to dělají dokonale |
| Klasifikace: Added, Fixed, Changed, Deprecated, Removed, Security | První průchod, lidské přepsání | Asi 80% správně jen z metadat; nesprávných 20% jsou záznamy, na kterých záleží |
| Výběr a formulace: co říct čtenáři, a jak | Nikdy | To je celá hodnota artefaktu |
| Zveřejnění: stránka, kanál, e-mail, widget, Slack | Zcela, z jednoho zdroje | Kam skutečně jde většina ručního úsilí |
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.
- 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.
- Kdokoli může kdykoli upravit jakýkoli koncept, a úprava je levná. Většina dostane přepsaný jeden řádek.
- 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.
- 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í.
Open-source nástroje dobře pokrývají kroky 1 a 4. git-cliff a conventional-changelog sestaví koncept z commit zpráv; release-please a semantic-release navíc zvolí verzi a vydání vystřihnou; Changesets nechá každý pull request nést vlastní ručně psanou poznámku, což se hodí pro monorepa; a GitHub umí generovat release notes ze sloučených pull requestů. Žádný z nich krok 3 nedodá.
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í. Pokud minuty utíkají na straně psaní, GitHub release notes ukazují, jak daleko vás vygenerovaný návrh dostane.
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.