Git tagy, release a váš changelog

Git tag, release a záznam changelogu jsou tři různé záznamy stejné události, a jejich zaměňování nechává changelog tiše odchýlit se od toho, co bylo skutečně vydáno. Tag označuje commit. Release balí tento tag s artefakty a popisem. Záznam changelogu vysvětluje, v termínech, které může použít čtenářka mimo repozitář, co se změnilo. Obvykle se dějí blízko sebe v čase, a přesně proto je snadné zacházet s nimi jako s jedním krokem místo tří, a přesně proto se propast stane viditelnou až měsíce později, když se někdo zeptá „co vyšlo ve v2.4” a čestná odpověď vyžaduje skutečné pátrání.

Jaký je skutečný rozdíl mezi těmito třemi?

Tag je z těch tří nejmechaničtější: git tag v2.4.0 a hotovo, bez jakéhokoli požadavku, aby něco vysvětlovalo, co obsahuje. Release přidává popis a obvykle stahovatelné artefakty, a jeho publikum zůstávají vývojářky, které vědí, co je stránka release. Záznam changelogu je jediný ze tří napsaný pro čtenářku, která možná nikdy repozitář neotevře, proto je to ten, který potřebuje nejvíc redakční pozornosti a nejsnáz se přeskočí pod tlakem termínů.

Potřebuje každý git tag záznam changelogu?

Ne, a zacházet s nimi jedna ku jedné je běžná chyba. Tag může označovat interní milník, release candidate, nebo hotfix, který se k většině uživatelek nikdy nedostane; žádný z nich nemusí nutně potřebovat veřejný záznam. Test je stejný, který rozhoduje, jestli něco vůbec patří do changelogu: jestli by si toho uživatelka nebo volající strana všimla nebo jí na tom záleželo. Většina tagů tímto testem projde. Některé, jako tag vytvořený jen kvůli spuštění CI pipeline, nikdy.

Potřebuje každý záznam changelogu vlastní tag?

Ne vždy, a tady se rozcházejí týmy s kontinuálním nasazením od týmů, které vydávají verzované balíčky. SaaS produkt, který nasazuje několikrát denně, může seskupit víc nasazení pod jeden datovaný záznam changelogu bez tagu 1:1 na nasazení; knihovna publikovaná v registru balíčků obvykle potřebuje tag na publikovanou verzi. Moduly Go a Swift Package Manager řeší verze přímo z tagů; na npm nebo PyPI drží publikovanou verzi registr, a tag je způsob, jak kdokoli tu verzi dohledá zpět k jejímu zdroji. Repozitář s několika nezávisle verzovanými balíčky musí tohle rozhodnout na balíček, ne jednou pro celé repo; changelogy v monorepu pokrývá, jak by prefixy tagů a rozsah changelogu měly sledovat hranice balíčků, ne složek. Semantic versioning a váš changelog pokrývá, jak by se samotné číslo verze mělo mapovat na kategorie changelogu; tagy jsou mechanismus, který dělá číslo verze ověřitelným proti skutečnému kódu.

Jak by měl popis release souviset se záznamem changelogu?

Mohou to být tytéž texty, ale jen pokud je publikum obou skutečně stejné, což je vzácnější, než se zdá. Stránku release na hostingu kódu čtou téměř výhradně vývojářky; pokud produkt má i netechnické uživatelky, které čtou changelog, doslovné duplikování popisu release posílá interní termíny a formulaci orientovanou na kód čtenářce, která potřebovala verzi v prostém jazyce. Nejčistší vzor: napsat záznam changelogu jako primární artefakt orientovaný na čtenářku, a nechat popis release buď na něj odkazovat, nebo si nechat kratší, technič­tější shrnutí pro publikum, které je tam už pohodlné.

# Release v2.4.0 (GitHub, pro vývojářky)
Povyšuje pipeline reportů na nový agregační engine. Viz changelog pro
shrnutí orientované na zákaznice:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orientovaný na zákaznice)
### Added
- Reporty se teď načítají za méně než sekundu, dokonce i pro účty s
  více než milionem řádků.

Stejný release, dva dokumenty, každý s vlastní formulací pro vlastní čtenářku.

Odkud skutečně pochází záznam changelogu?

Ze dvou výchozích bodů, a většina reálných pipeline je směsí obou. Může se generovat z commit zpráv v okamžiku tagu, což je rychlé a nikdy nevynechá sloučený pull request; od conventional commits k changelogu pokrývá tuhle pipeline celou. Nebo se může psát ručně, zcela odděleně od tagu, časovaný na okamžik, kdy je funkce považována za hotovou, místo na okamžik, kdy se kód sloučí. Generované záznamy jsou konzistentní, ale dědí každou nejasnou commit zprávu; ručně psané záznamy jsou jasnější, ale potřebují někoho, kdo je skutečně napíše. Většina týmů, které automatizují, si stejně nechává lehký redakční průchod na vygenerovaném textu, než se stane veřejným záznamem, stejná disciplína, jakou doporučuje Keep a Changelog v praxi, bez ohledu na to, odkud surový text původně pocházel.

Co se rozbije, když se tyto tři rozejdou?

Důvěra v to, co čtenářka zkontrolovala jako první. Tag, který existuje bez odpovídajícího záznamu changelogu, vypadá, ze strany čtenářky changelogu, jako by se ten týden nic nestalo. Záznam changelogu bez odpovídajícího tagu nebo release znemožňuje tomu, kdo ladí produkční problém, checkoutovat přesně ten kód, který byl live, když byl záznam publikován. Řešením není dokonalá automatizace, ale jediný zdroj pravdy pro toto propojení: jedno místo, klidně jen vlastní checklist procesu release, které říká, že vydatelná změna dostane všechny tři, ve stejném commitu nebo pull requestu, který ji zavádí.

FAQ

Měly by se záznamy changelogu generovat automaticky z git tagů? Mohou být výchozím bodem, ale samotný tag nenese žádný popis orientovaný na čtenářku, jen rozsah commitů. Automatizovaná generace musí číst commit zprávy uvnitř tohoto rozsahu, ne jen existenci tagu, aby vyprodukovala něco použitelného.

Co když netagujeme každý release? Pak se záznam changelogu stane primárním záznamem, a stejně by měl nést datum a, pokud produkt nějakou má, číslo verze, aby záznam zůstal něčím, na co se čtenářka může později odkázat, i bez odpovídajícího tagu.

Měly by pre-release tagy (jako v2.4.0-rc.1) mít záznamy changelogu? Obecně ne. Release candidate je pro interní nebo beta testování, a záznam changelogu pro něj učí čtenářky očekávat záznamy pro verze, které nemusí nikdy vyjít přesně tak, jak byly popsány. Nechte si záznamy pro tagy, které dosahují obecné dostupnosti.

Může jeden záznam changelogu pokrýt víc git tagů? Ano, a pro týmy, které tagují často, by často měl. Seskupte související tagy pod jeden datovaný záznam popisující čistou změnu, místo publikování tenkého záznamu na tag, který fragmentuje funkci přes víc čtení.

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, Dokumentace pro vývojáře