Co je changelog a co by měl obsahovat?

Changelog je datovaný záznam toho, co se v produktu změnilo, napsaný pro lidi, kterých se změna týká, ne pro tým, který ji vydal. Každý záznam pojmenovává jednu změnu, říká, kdy vstoupila v platnost, a říká, co s tím má čtenářka dělat, což u většiny záznamů znamená nic. Právě tahle poslední část odděluje changelog od commit logu: commit log je záznam pro ty, kdo napsali kód, changelog je záznam pro ty, kdo ho používají.

Co je changelog, přesně?

Seznam datovaných záznamů, nejnovější první, každý popisuje jednu změnu v termínech, které si čtenářka může ověřit. Ne to, co tým postavil, ale co je teď jinak. “Refaktorování fakturační služby” je commit zpráva. “Faktury teď ukazují daň jako samostatný řádek” je záznam changelogu, protože říká čtenářce něco, co si může ověřit na vlastním účtu.

Formát je starý a záměrně jednoduchý: nadpis na release nebo den, krátký seznam pod ním, někdy štítek kategorie. Keep a Changelog je nejcitovanější specifikace této podoby, a existuje proto, že většina projektů, které specifikaci přeskočí, skončí u vysypání historie commitů místo ní, což odpovídá na jinou otázku, než s jakou čtenářka přišla.

Těchto pět se v praxi překrývá, ale nejde o stejný dokument, a rozdíl je v tom, kdo ho drží v ruce v okamžiku čtení. Changelog je ten, který je postavený tak, aby se v něm dalo vyhledávat a později na něj odkazovat, proto jeho záznamy potřebují stabilní data a URL víc než ostatní.

Co záznam changelogu skutečně obsahuje?

Čtyři věci, v tomto pořadí: co se změnilo, formulováno v termínech, které by si všimla uživatelka nebo volající strana; kdy to vstoupilo v platnost; do jaké kategorie to patří (added, fixed, changed, removed jsou čtyři běžné); a když na tom záleží, co s tím má čtenářka dělat. Odkaz na další detaily je vítaný. Odstavec interního zdůvodnění ne, protože čtenářka se neptala proč, ptala se co.

## 2026-09-07

### Added
- Faktury teď ukazují daň jako samostatný řádek, v měně účtu zákazníka.

### Fixed
- Export reportu jako CSV už neztrácí poslední řádek, když report
  přesáhne 10 000 řádků.

Tahle podoba škáluje od aktualizace o dvou řádcích až po sto záznamů v jednom releasu, aniž by se měnila struktura, a to je skutečný test toho, jestli formát funguje: čte se stejně v nabitém týdnu jako v klidném.

Kdo píše changelog, a kdy?

Ta, kdo změnu udělala, v okamžiku vydání, ne technická redaktorka, která ho rekonstruuje z ticketů o týden později. Ta, kdo se dotkla kódu, ví, co se pro uživatelku skutečně změnilo; shrnutí napsané dodatečně má tendenci popisovat ticket místo toho, co se skutečně vydalo, a to bývá širší nebo užší než skutečný rozsah. Některé týmy přidávají krok revize předtím, než se záznam stane veřejným, hlavně aby zachytily interní jazyk, který se do něj vplížil, a tahle revize by měla být dost rychlá, aby záznam vyšel ještě týž den.

Kde by měl changelog žít?

Na vlastní stránce, na stabilní URL, distribuovaný jako feed. Zahrabaný v menu nastavení nebo v release tagu na hostingu kódu, dosáhne jen na ty, které už věděly, kam se dívat. Na veřejnou stránku se dá odkázat z ticketu podpory, citovat v recenzi, nebo ji odebírat. Feed je stejně důležitý jako stránka: čtenářka, která kontroluje changelog produktu jednou za měsíc, je vzácná, ta, co ho odebírá, ne, a jen feed slouží té druhé skupině.

Čím se liší od poznámek k vydání?

Tyhle dva se neustále zaměňují, a jsou dost odlišné na to, aby jejich smíchání vytvořilo dokument, který dobře neslouží žádné z obou čtenářek. Changelog versus poznámky k vydání prochází rozdíl celý; krátce, changelog je úplný, chronologický záznam, a poznámky k vydání jsou vybraná podmnožina, napsaná tak, aby aktualizace zněla, že za ni stojí. Produkt obvykle potřebuje oba, zaměřené na různé okamžiky v čtenářčině dni.

Co dělá changelog hodným přečtení?

Konkrétnost a poctivost o vlastním rozsahu. “Různé opravy chyb” je věta, která čtenářku naučí přestat stránku otevírat, protože neslibuje nic, co by si mohla ověřit. Záznam, který pojmenovává přesné chování, jež se změnilo, i u malé opravy, je ten, který drží odběr naživu. Tahle disciplína platí i pro to, co se vynechává: changelog, který oznamuje jen úspěchy a nikdy opravu něčeho rozbitého, se čte jako marketing v přestrojení za changelog, a čtenářky si toho všimnou.

Záleží i na disciplíně verzování. Semantic versioning a váš changelog ukazuje, jak by si číslo verze a záznam měly odpovídat, aby čtenářka, která prochází historii verzí, dostávala stejný signál dvakrát místo dvou různých.

Jak se changelogy generují?

Dvěma způsoby, a většina reálných nastavení je mix. Automatizované generování čte commit zprávy, obvykle ve formátu Conventional Commits, a mění je na záznamy, aniž by se kdokoli dotkl výstupu; od conventional commits k changelogu pokrývá tuhle pipeline. Kurátorované generování znamená, že někdo každý záznam napíše nebo upraví ručně. Automatizovaný výstup je rychlejší a nikdy nevynechá sloučený pull request, ale zdědí každou nejasnou commit zprávu doslovně, takže většina týmů, které automatizují, si stejně před publikací nechává lehký redakční průchod místo zobrazení syrového výstupu.

FAQ

Potřebuje každý produkt changelog? Potřebuje ho každý produkt s uživatelkami, kterých se změna dotýká, ať jde o SaaS aplikaci, interní nástroj, nebo veřejné API. Podoba se přizpůsobuje (changelog API se čte jinak než u spotřebitelské aplikace), potřeba ne.

Co je changelog softwarovými termíny? Stejná definice jako výše: datovaný, chronologický seznam toho, co se v softwaru změnilo, napsaný pro ty, kdo ho používají, ne pro ty, kdo ho postavili.

Může se changelog generovat automaticky z commitů? Ano, a mnoho týmů dělá přesně tohle, obvykle ze zpráv ve formátu Conventional Commits. Kompromis je v tom, že vygenerovaný záznam je jen tak jasný jako commit zpráva, ze které pochází, takže redakční průchod před publikací zachytí ty, které potřebují přeformulovat.

Je changelog totéž co historie verzí? Dost blízko na to, aby se termíny používaly zaměnitelně. Historie verzí je někdy jen seznam čísel verzí a dat bez popisu; changelog vždy obsahuje, co se změnilo.

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