Semantic versioning a váš changelog

Semantic versioning říká volající straně, jak moc může bolet release, ještě než přečte jediný záznam changelogu. Přechod z 2.4.1 na 2.5.0 říká: nová schopnost, nic se nerozbije. Přechod z 2.5.0 na 3.0.0 říká: přečti si tenhle záznam před aktualizací. Changelog a číslo verze mají tvrdit totéž ve dvou formátech, a většina tření mezi nimi se objeví právě tehdy, když se neshodnou, což se stává častěji, než by specifikace naznačovala.

Co vlastně slibuje každé číslo ve verzi?

Semantic versioning definuje tři čísla, MAJOR.MINOR.PATCH, každé s přísným pravidlem o tom, co ho spouští. Skok MAJOR znamená nekompatibilní změnu: něco, čeho by si mohla všimnout správná, existující integrace, a kvůli čemu by se musela změnit. Skok MINOR znamená novou, zpětně kompatibilní funkčnost: nic existujícího se nerozbije, něco nového je k dispozici. Skok PATCH znamená zpětně kompatibilní opravu: chování se přibližuje tomu, co bylo dokumentováno, a nikdo, kdo se záměrně spoléhal na staré chování, by si neměl ničeho všimnout.

Tabulka je i test naopak: pokud se záznam nečte jako jeho řádek, buď je číslo verze špatně, nebo záznam podhodnocuje či nadhodnocuje to, co se skutečně stalo.

Co se počítá jako nekompatibilní pro účely verzování?

Stejný test, který rozhoduje, jestli něco patří do changelogu API: jestli by se správná volající strana, napsaná proti starému chování a od té doby nedotčená, mohla chovat jinak kvůli téhle změně. Co je nekompatibilní změna, a jak ji vydat pokrývá rozhodnutí celé, včetně případů, které vypadají nekompatibilně, ale nejsou, a těch, co vypadají malé, ale nejsou. Krátce pro účely verzování: pokud je odpověď ano, skok je MAJOR bez ohledu na to, kolik kódu změna skutečně zasáhla interně. Čísla verzí sledují důsledek pro volající stranu, ne úsilí týmu.

Jak by měl záznam changelogu odpovídat skoku verze?

Jeden záznam, jedna kategorie skoku, uvedená hned na začátku. Vzorec z tabulky pokračuje přímo: nekompatibilní záznam stojí pod verzí, která ho zavedla, formulovaný nejdřív jako varování, pak jako popis. Přídavný záznam stojí pod svou MINOR verzí, formulovaný jako dostupnost. Oprava stojí pod svou PATCH verzí, formulovaná jako náprava. Míchání kategorií v jednom záznamu, třeba zabalení nekompatibilní změny do stejného odstavce jako nesouvisející opravy, je způsob, jak čtenářka mine právě to jedno, na čem skutečně záleželo.

## 3.0.0 (2026-09-07)

### Changed
- **BREAKING:** `GET /reports` teď vrací částky jako celá čísla v
  nejmenší měnové jednotce (halířích) místo desetinných čísel.
  Aktualizujte kód, který čte `amount` přímo.

## 2.9.0 (2026-09-01)

### Added
- Reporty teď lze filtrovat podle `status`.

## 2.8.4 (2026-08-28)

### Fixed
- `GET /reports?status=` vracelo prázdnou stránku místo 400 pro
  neznámý status.

Čteno shora dolů, číslo verze a štítek sekce říkají totéž dvakrát, a přesně o to jde: čtenářka, která projede jen nadpisy, dostane správný odhad rizika ještě před otevřením jediného řádku.

Platí pravidlo o nekompatibilní změně stejně i před verzí 1.0.0?

Ne, a právě odsud pochází většina zmatku kolem „bylo to vlastně breaking”. SemVer výslovně říká, že hlavní verze nula, 0.y.z, je pro počáteční vývoj: cokoli se může kdykoli změnit a veřejné API by se nemělo považovat za stabilní. Skok z 0.4.0 na 0.5.0 může nést nekompatibilní změnu, aniž by porušil specifikaci, protože záruka hlavní verze začíná platit až od vydání 1.0.0. Záznam changelogu pořád dluží čtenářce stejnou poctivost o tom, co se rozbilo; mění se jen to, že samotné číslo verze není signál, na který se dá spolehnout před příchodem 1.0.0.

Co když váš produkt nevydává diskrétní verze?

Většina SaaS produktů nasazuje průběžně a nikdy volající straně nezobrazuje číslo verze, což nezbavuje potřeby téhle disciplíny, jen čísla, které by ji normálně neslo. Záznam changelogu musí odvést celou práci sám: jasně říct, jestli je změna nekompatibilní, přídavná, nebo oprava, stejnými třemi slovy, jaká používá semantic versioning, i bez pole verze, kam by je připnul. Některé týmy si drží čistě interní verzi jen proto, aby ukotvily záznamy changelogu k něčemu, na co se dá odkázat, aniž by ji kdy ukázaly přímo volající straně.

Jak se to vztahuje konkrétně na changelog API?

Přísněji než skoro kdekoli jinde, protože volající strany API jsou kód, ne lidé, kteří mohou nad neočekávanou změnou pokrčit rameny. Changelog API: co publikovat a kdo ho čte pokrývá plnou podobu tohoto dokumentu; disciplína verzování zde je to, co drží jeho sekce breaking a přídavné poctivé. API, které nabízí několik verzí najednou, třeba v1 a v2 obsluhované paralelně během migračního okna, fakticky aplikuje semantic versioning na úrovni celého rozhraní místo jednoho balíčku, a stejná trojslovná slovní zásoba stále platí pro každý záznam.

Co říká Keep a Changelog o verzování?

Váže se přímo jménem na semantic versioning a doporučuje stejnou slovní zásobu kategorií, jakou používá tenhle článek: Added, Changed, Deprecated, Removed, Fixed, Security. Keep a Changelog v praxi prochází, jak tuhle specifikaci přijmout, včetně míst, kde se týmy obvykle odchylují. Překryv není náhoda: obě specifikace se snaží vyřešit stejný problém z opačných konců, jedna standardizuje číslo verze a druhá záznam, který ho vysvětluje.

FAQ

Potřebuje každý záznam changelogu číslo verze? Pokud produkt vydává verze, ano, protože číslo umožňuje čtenářce skočit rovnou k “jak moc se mě to týká”, aniž by nejdřív četla záznam. Pokud produkt nasazuje průběžně bez pole verze, formulace záznamu musí ten signál nést sama.

Jaký je rozdíl mezi skokem MAJOR a záznamem o nekompatibilní změně? Měly by popisovat stejnou událost dvěma způsoby. Číslo verze je signál čitelný strojem (nástroje volající strany na něj mohou reagovat); záznam changelogu je člověku čitelné vysvětlení toho, co se konkrétně změnilo.

Může být PATCH release nekompatibilní? Podle definice by neměl. Pokud takový přesto vyšel, publikovanou verzi neupravujte ani jí neměňte tag: FAQ SemVer radí vydat novou verzi, která kompatibilitu obnoví, nebo novou MAJOR verzi, pokud nekompatibilita zůstává, a problematickou verzi zdokumentovat, aby uživatelé věděli, že ji mají přeskočit.

Potřebují čistě interní změny skok verze? Ne. Semantic versioning sleduje veřejné rozhraní. Refaktoring bez pozorovatelného efektu pro volající stranu nepotřebuje ani skok, ani záznam changelogu, i kdyby to interně byla významná inženýrská práce.

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