CHANGELOG.md: co do něj patří a jak ho udržet aktuální

CHANGELOG.md je soubor v Markdownu v kořeni repozitáře, který pro každou vydanou verzi vypisuje, co se změnilo, slovy, se kterými může uživatel projektu něco udělat. Soubor čtou lidé, kteří se rozhodují, zda aktualizovat, lidé, kteří po aktualizaci ladí problém, a registry balíčků a release nástroje, které ho vykreslují na stránce projektu. Formát, který většina projektů dodržuje, je ten popsaný na keepachangelog.com: nejnovější verze nahoře, nad ní sekce Unreleased a záznamy seskupené pod Added, Changed, Deprecated, Removed, Fixed a Security.

Co je soubor CHANGELOG.md?

Je to lidsky čitelná historie projektu, verze po verzi, uložená vedle kódu, aby se dodávala s ním. Od git log se liší publikem a výběrem: git log zaznamenává každý commit pro lidi, kteří ho napsali, zatímco changelog zaznamenává změny, kterých by si uživatel všiml, napsané pro člověka, který je nenapsal. Commit, který přejmenuje interní proměnnou, nemá v changelogu řádek. Commit, který mění výchozí timeout, ho má, i když byl diff jediný znak.

Soubor žije v kořeni repozitáře přesně pod tímto jménem, protože ho tam hledají nástroje. GitHub na něj odkazuje ze stránky repozitáře, npm a PyPI ho vykreslí, když je součástí balíčku, a release nástroje jako release-please a semantic-release ho na místě čtou a zapisují. Malé changelog.md a CHANGES.md pro lidi fungují také, ale některé nástroje hledají jen kanonické jméno.

Jak vypadá úplný CHANGELOG.md?

Krátký správný příklad má větší cenu než dlouhý popis. Tento dodržuje rozvržení Keep a Changelog 1.1.0 a sémantické verzování pro čísla.

# Changelog

Všechny podstatné změny tohoto projektu jsou uvedeny zde.
Formát: Keep a Changelog. Verze: sémantické verzování.

## [Unreleased]

### Added
- Přepínač `--dry-run` u `deploy` vypíše plán bez jeho provedení.

## [2.3.1] - 2026-10-01

### Fixed
- Vyhledávání už neselhává u dotazů obsahujících pomlčku.
  Rozbité od 2.3.0.

### Security
- Opraven path traversal v handleru statických souborů.
  Aktualizujte ještě dnes, pokud servírujete soubory nahrané
  uživateli.

## [2.3.0] - 2026-09-18

### Added
- Streamovaný export. Soubory nad 100 MB už nevyprší.

### Deprecated
- `legacyAuth()` stále funguje, ale bude odstraněno ve 3.0.
  Použijte `auth()`.

[Unreleased]: https://github.com/acme/tool/compare/v2.3.1...HEAD
[2.3.1]: https://github.com/acme/tool/compare/v2.3.0...v2.3.1
[2.3.0]: https://github.com/acme/tool/compare/v2.2.0...v2.3.0

Čtyři detaily nesou většinu hodnoty. Každá verze má datum ve formátu ISO, takže si ho čtenář může porovnat s tím, kdy jeho problém začal. Každý nadpis verze je odkaz na porovnání, takže úplný diff je na jedno kliknutí. Oprava říká, která verze to rozbila. A sekce Security stojí stranou, takže ten, kdo hledá odpověď na «musím aktualizovat hned», ji najde během vteřin.

Jak udržet CHANGELOG.md aktuální?

Napište řádek ve stejném pull requestu jako změnu, pod Unreleased, a při vydání sekci přesuňte pod nadpis verze. To je celá metoda. Soubor zastarává, když řádek píše později někdo jiný, v době vydání, ze seznamu zpráv commitů, které nenapsal.

Dvě věci pomáhají, aby návyk držel. První je kontrola v CI, která nechá spadnout pull request, jenž sahá do src/ a nesahá do changelogu, se štítkem pro přeskočení u změn bez viditelného efektu pro uživatele; kontrola changelogu jako GitHub Action ukazuje čtyřicetiřádkovou verzi. Druhá je krok vydání, který jedním příkazem přejmenuje Unreleased na verzi a datum, aby na to nikdo nemusel myslet ručně. Kdo píše changelog popisuje, jak týmy řeší otázku, čí práce ten řádek je.

Má se changelog generovat z commitů?

Generování vám dá úplný návrh; nedá vám changelog. Nástroje postavené na conventional commits a release automatizace jako release-please čtou prefixy feat:, fix: a BREAKING CHANGE: a vytvoří seskupený seznam s odkazem na každý pull request. Seznam je jen tak dobrý jako předměty commitů, a předměty commitů popisují kód.

Použitelný střed je generovat a pak upravit. Nechte nástroj vytvořit sekci Unreleased z commitů a v release pull requestu přepište řádky, které by četl uživatel: příznak místo názvu funkce, nastavení, které se přesunulo, místo souboru, který se změnil. Od conventional commits k changelogu prochází celou pipeline a generátor changelogu v prohlížeči stačí k tomu, abyste dostali návrh z vloženého git log bez instalace čehokoli.

Co do CHANGELOG.md nepatří?

Interní refaktory, zvýšení verzí závislostí bez změny chování, commity jen s testy, konfigurace CI a změny formátování. Patří do historie gitu, kde je každý, kdo je potřebuje, najde. Jejich zahrnutí zahrabe řádky, na kterých záleží, a naučí čtenáře soubor přeskakovat.

Druhá věc, kterou vynechat, je marketingová verze změny. «Bleskově rychlé exporty» neřeknou čtenáři nic, co by si mohl ověřit. «Export teď streamuje; soubory nad 100 MB už nevyprší» ano. Soubor je referenční dokument a tón tomu má odpovídat: krátké řádky, konkrétní podstatná jména, verze nebo datum u všeho. Keep a Changelog, skutečně zavedený rozebírá části specifikace, které týmy nejčastěji vypouštějí, a formáty souborů changelogu říkají, kdy se zdroj v JSON nebo YAML vedle Markdown souboru vyplatí.

Potřebuje produkt se stránkou changelogu ještě soubor?

Knihovna ano, protože soubor je to, co registry balíčků vykreslují a co vývojář čte offline. SaaS produkt bez instalovatelného artefaktu vystačí se samotnou stránkou, protože jeho uživatelé repozitář nikdy nevidí. Mnoho týmů provozuje obojí: soubor jako inženýrský záznam a veřejnou stránku changelogu, která se z něj píše pro širší publikum, s detailem rozděleným tak, jak popisuje changelog vs release notes. Pokud se stránka plní ze souboru, nechte soubor zdrojem pravdy a stránku generujte, aby existovalo jediné místo k úpravám.

FAQ

Jaký je rozdíl mezi CHANGELOG.md a release notes? Changelog je úplný průběžný záznam každé podstatné změny, uložený v repozitáři. Release notes jsou zpráva o jednom vydání, často kratší a přepsaná pro širší publikum. Mnoho projektů zveřejňuje sekci changelogu pro danou verzi jako její release notes.

Kde má CHANGELOG.md žít? V kořeni repozitáře, přesně pod tímto jménem, aby ho GitHub, registry balíčků a release nástroje našly. Monorepo má jeden na balíček, vedle manifestu každého balíčku.

Mám CHANGELOG.md generovat z git commitů? Vygenerujte návrh a pak upravte řádky, které bude číst uživatel. Zprávy commitů popisují změnu kódu; changelog popisuje, čeho si všimne uživatel. Nástroje jako conventional-changelog a release-please dají dobrý výchozí bod.

Potřebuje každý commit záznam v changelogu? Ne. Jen změny, kterých si uživatel projektu mohl všimnout: nová schopnost, změněné chování, deprekace, odstranění, opravy a bezpečnostní záplaty. Refaktory, změny testů a úpravy CI zůstávají v historii gitu.

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, Příklady changelogu