Keep a Changelog, skutečně zavedený

Keep a Changelog je jednostránková konvence pro CHANGELOG.md: nejnovější verze první, jedna sekce na verzi s číslem a datem ISO, záznamy seskupené pod šesti typy (Added, Changed, Deprecated, Removed, Fixed, Security), a sekce Unreleased nahoře pro záznamy mezi vydáními. Většina týmů, které ji citují, zavádí asi dvě třetiny z ní, a třetina, kterou vynechávají, je ta třetina, která chrání jejich uživatele.

Olivier Lacan zveřejnil Keep a Changelog v roce 2014 s větou, která zestárla lépe než většina softwarové prózy: don’t let your friends dump git logs into changelogs. O deset let později je to nejbližší standardu, který tento koutek softwaru má. Stojí za to přečíst zdroj místo shrnutí; tento text je o částech, které se vynechávají.

Co Keep a Changelog vyžaduje?

CHANGELOG.md v kořeni repa, nejnovější první, s jednou sekcí na verzi. Každá verze nese číslo a datum ISO, a seskupuje své záznamy pod šesti typy:

Plus sekce Unreleased nahoře, aby bylo místo, kam vložit záznam v okamžiku jeho sloučení, a aby kdokoli mohl vidět, co přichází.

To je téměř vše. Zbytek je odůvodnění: záznamy jsou pro lidi, jeden záznam na změnu, a soubor je dokument spíše než log.

Které části Keep a Changelog se vynechávají?

Sekce Unreleased, pak čtyři ze šesti typů, Security mezi nimi, v tomto pořadí.

Unreleased mizí první. Je to sekce bez termínu, takže je to ta, jejíž údržba přestává jako první, a jakmile zmizí, záznamy se píší v okamžiku vydání z historie commitů. To je přesně ten výpis git logu, před kterým specifikace varuje hned na začátku, dosažený postupně. Automatizace changelogu je z velké části o udržení této sekce naživu, aniž by si na to musel kdokoli pamatovat.

Šest typů se zhroutí do dvou. Většina skutečných changelogů skončí s Added a Fixed, protože Changed a Deprecated vyžadují úsudek o tom, na co se kdo spoléhal. Tento úsudek je hodnotná část. Deprecated je zejména jediný typ, který je slibem o budoucnosti, a jeho vynechání je způsob, jak se odstranění promění v incident; mechanika dodržení tohoto slibu je v jak deprekovat API.

Security přestává být oddělené. Bezpečnostní oprava zařazená pod Fixed je neviditelná pro jedinou čtenářku, která ji hledala. Udržujte ji odlišnou i tehdy, když je oprava triviální, a zejména když byste raději na ni nechtěli upozorňovat.

Co specifikace neřeší?

Je to formát souboru. Neříká nic o otázkách, na které narazíte hned po jejím přijetí:

• Jak se to kdo dozví? Soubor v repu se dostane k přispěvatelům. Nedostane se k zákaznici, která nikdy neotevřela GitHub.
• Co produkty bez verzí? Kontinuálně nasazovaná služba nemá v4.2.0, podle které by seskupovala. Většina týmů to nahradí daty, což funguje, a specifikace to ani nepožehná, ani nezakazuje.
• Kdo píše záznam? Specifikace předpokládá, že to dělá člověk. Neříká kdy.
• Co více publik? Jeden soubor slouží vývojářům. Neslouží stejným obsahem netechnické administrátorce, a ruční přeformátování pro ni je místo, kde začíná duplicita. Changelog vs release notes je rozdělení, které specifikace nechává na vás.

Common Changelog, přísnější rozdvojení této myšlenky, něco z toho zpřísňuje: zakazuje určité formulace záznamů, vyžaduje odkaz na změnu, a má jasný názor na to, kdo je čtenář. Stojí za přečtení, pokud jsou volné části Keep a Changelog to, o čem se váš tým neustále hádá.

Lze Keep a Changelog automatizovat bez výpisu git logů?

Ano: odvoďte koncept ze strukturovaných commitů, umístěte ho do Unreleased s předvyplněným typem, a vyžadujte, aby člověk upravil formulaci před vydáním. Varování specifikace se týká výstupu, ne nástroje. Odvození konceptu z commitů je v pořádku. Zveřejnění tohoto konceptu bez úprav je to, proti čemu se staví.

Stroj se stará o sběr a formátování, v čem je dobrý. Člověk se stará o výběr a formulaci, v čem dobrý není. Conventional commits rozebírají dvouvrstvé rozdělení, na kterém tohle staví, a které typy commitů se mapují na které z šesti kategorií výše. Náš přehled nástroje pro changelog pokrývá, co existuje pro polovinu sběru.

Kde Keep a Changelog přestává být dostatečný?

Zastavuje se u distribuce. Keep a Changelog je dobrá odpověď na «jak by měl tento soubor vypadat». Není to odpověď na «jak se naši uživatelé dozví, co se změnilo», protože soubor Markdown v repu je distribuční strategie, která funguje jen pokud jsou vaši uživatelé přispěvatelé.

To je překážka, na kterou většina týmů narazí jako druhou: soubor je v pořádku, a nikdo mimo tým ho nečte. Vyřešení znamená, že záznamy se musí stát daty, která lze vykreslit jinde, což je jiný problém než formátování souboru, a důvod, proč příklady changelogu shromažďuje veřejné stránky changelogu spíše než soubory repozitáře. Jak proměnit tyto záznamy v něco, k čemu se lidé vracejí, řeší jak postavit changelog stránku.

Specifikaci přesto zaveďte. Stojí odpoledne, dělá druhý problém zvládnutelným, a stále je to nejlepší stránka, jaká byla kdy o tomto napsána.

FAQ

Je Keep a Changelog standard? Je to široce přijatá konvence, ne specifikace normalizačního orgánu. Nástroje (skripty pro vydání, lintery, parsery) dostatečně často předpokládají jeho formu, že jeho dodržování kupuje kompatibilitu.

Co patří do sekce Unreleased? Každý záznam pro změnu, která byla sloučena, ale ještě nebyla vydána v číslovaném vydání. Když se vydání vystřihne, sekce se přejmenuje na verzi a datum, a nová, prázdná sekce Unreleased jde nad ni.

Měl by changelog používat sémantické verzování? Keep a Changelog to doporučuje a nevyžaduje. Knihovny a API z toho profitují; kontinuálně nasazovaná služba obvykle nahrazuje daty, což formát umožňuje.

Měly by bezpečnostní opravy být v changelogu, než jsou veřejné? Přidejte záznam, když je oprava vydána, s dostatečnou podrobností, aby operátor mohl jednat, a ne více. Odklad záznamu do data koordinovaného zveřejnění je normální; jeho vynechání ne.

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: Příklady changelogu, Srovnání nástrojů pro changelog