Od conventional commits k changelogu

Conventional commits dávají changelogu zdarma tři věci: typ každé změny, část systému, které se dotkla, a zda něco rozbíjí. Nedávají nic víc. Formulace, seskupování a výběr, což je changelog, zůstávají zcela otevřené, a pipeline, který předstírá opak, dodá naformátovaný git log.

feat(exports): add CSV column selection
fix(auth): reject expired refresh tokens
chore(deps): bump node-pg to 8.11

Tři commity ve formátu Conventional Commits. Z nich vám stroj může říct, že jeden je funkce, jeden oprava, jeden úklid, a které části systému se každý dotkl. To je skutečně užitečné, a je to celý slib konvence: historie commitů, kterou dokáže číst něco jiného než člověk. Chyba je myslet si, že vám to dá changelog. Dá vám to surovinu.

Co konvence specifikuje?

Typ, volitelný scope, a popis: type(scope): description. Typy jsou konvenčně feat, fix, chore, docs, refactor, test, perf, build, ci. Dvě věci označují breaking change: ! před dvojtečkou, nebo footer BREAKING CHANGE:. Nástroje se řídí feat a fix pro minor a patch verze, a breaking markerem pro major.

Marker to sděluje nástroji; nesděluje to volající straně, což je téma jak deprekovat API a co je breaking change. Je to malá specifikace a vyplatí se ji dodržovat, i když z ní nikdy nic negenerujete, protože vynucuje jedno rozhodnutí na commit: je to změna, kterou uživatelé vidí, nebo ne.

Kde se conventional commits zastavují?

Zastavují se u věty. Vše, co konvence zachytí, jsou metadata o změně; samotná změna je stále popsána slovníkem recenzentky.

Zprávy commitů jsou napsány pro recenzentky. fix(auth): reject expired refresh tokens je správně a nic to zákaznici neřekne. Čtenářka changelogu chce «budete odhlášeni, když relace skutečně vyprší, místo občasných 401».

Scope jsou interní. exports, auth, ingest jsou názvy modulů. Jsou stabilní, což je dělá dobrými pro seskupování, a bezvýznamnými pro kohokoli mimo kódovou základnu.

Jedna změna je často více commitů. Funkce sloučená přes jedenáct commitů vytvoří jedenáct záznamů, deset z nich šum, a jejich stlačení, aby se to skrylo, ztratí historii revize.

chore je koš, ne kategorie. Aktualizace závislostí, změny CI a přejmenování tam všechny padají, a některé záleží uživatelům, zatímco většina ne.

Takže: konvence vám dá typ, scope a stav breaking zdarma, a nechá formulaci, seskupování a výběr zcela otevřené. Tyto tři jsou changelog. Kdo je vlastně odpovědný za záznam v changelogu rozebírá, kdo by se měl postarat o tuhle formulaci, seskupování a výběr, protože samotná konvence na to nemá názor.

Jak se generuje changelog z conventional commits?

Ve dvou vrstvách, a druhá musí být povinná.

Vrstva první, automatická. Při merge odvoďte konceptový záznam z commitu: typ mapovaný na typ changelogu (feat na Added, fix na Fixed, breaking marker na Changed plus flag), scope udržovaný jako metadata místo textu, odkaz na PR. Umístěte ho do sekce Unreleased, kterou vyžaduje Keep a Changelog.

Vrstva druhá, lidská, a vyžadovaná. Než vyjde vydání, každý konceptový záznam buď dostane jednořádkový přepis do slovníku uživatele, nebo je označen jako interní a odstraněn z veřejného pohledu. Toto je krok, který se lidé snaží přeskočit, a jeho přeskočení produkuje changelogy, které se čtou jako diff.

Důležitý detail designu je, že vrstva druhá není v pipeline volitelná. Pokud lze vydání vystřihnout s neupravenými koncepty, stane se to, v týdnu, kdy jsou všichni zaneprázdnění. Které kroky patří stroji a které člověku je celý obsah automatizace changelogu.

Vystřihnutí release je taky okamžik, kdy git tag, release a tenhle záznam changelogu buď sedí dohromady, nebo se začnou rozcházet; git tagy, release a váš changelog pokrývá, jak udržet tyto tři synchronizované.

Tři pasti

Squash merge sní footery. Pokud vaše platforma slučuje s titulkem PR jako zprávou, footer BREAKING CHANGE: commitu uvnitř té větve zmizí, a vaše nástroje tiše přestanou vidět breaking change. Zkontrolujte, co vaše šablona squash skutečně zachovává.

Revert commity produkují fantomové záznamy. fix, který je následující den vrácen, vygeneruje záznam pro něco, co nikdy nebylo vydáno, pokud odvození nesladí revert. Většina nástrojů to nedělá.

Zvýšení verze a changelog se rozejdou. Pokud se verze počítá z commitů a changelog se píše ručně poté, rozejdou se přibližně za dvě vydání. Počítejte oba v témže průchodu nebo přijměte, že jeden z nich je špatně.

Pokud chcete mechanickou část bez pipeline

Náš generátor changelogu provádí krok odvození v prohlížeči: vložte commity, získejte seskupené, typizované záznamy. Je záměrně deterministický a zcela klientský, takže commity, které vložíte, nikdy neopustí váš stroj, což záleží, když zprávy pocházejí ze soukromého repozitáře. Poctivě dělá polovinu sběru a nezkouší vrstvu druhou, protože vrstva druhá je úsudek, a nástroj, který ho předstírá, produkuje přesně ten changelog, proti kterému tento článek argumentuje.

Pro pipeline verzi nástroje pro changelog pokrývá, co existuje.

Shrnutí

Conventional commits spolehlivě a levně odpovídají na «jaký druh změny to je». Neodpovídají na «co bychom měli říct lidem», a žádné množství nástrojů nad zprávou commitu to neudělá, protože informace nikdy nebyla ve zprávě commitu. Rozpočtujte na přepis.

FAQ

Generují conventional commits changelog automaticky? Generují automaticky koncept: typizované, se scope, propojené záznamy. Formulace pro zákaznici, seskupování a rozhodnutí, co vynechat, stále potřebují člověka, a pipeline, který tento krok přeskočí, zveřejňuje zprávy commitů.

Jaké typy conventional commit se objevují v changelogu? feat a fix vždy, jako Added a Fixed. perf obvykle, jako Changed. chore, docs, refactor, test, build a ci jsou ve výchozím nastavení interní a objevují se, jen pokud člověk jeden z nich povýší.

Jak conventional commits označují breaking change? ! po typu nebo scope (feat(api)!: ...), nebo footer BREAKING CHANGE: v těle commitu. Oba se ztratí, pokud squash merge zachová jen titulek PR.

Potřebujete conventional commits k automatizaci changelogu? Ne. Štítky PR, šablony PR a odkazy na issue nesou stejná metadata pro týmy, které slučují přes pull request. Conventional commits jsou nejlevnější možnost, když jednotkou změny je commit.

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: Generátor changelogu, Srovnání nástrojů pro changelog