Formáty souborů changelogu: JSON, YAML nebo jen Markdown

Většina týmů začíná changelog jako soubor Markdown, protože je to cesta nejmenšího odporu: čitelná v diffu pull requestu, čitelná na GitHubu bez renderování čehokoli, a známá každému, kdo kdy napsal README. Tahle volba funguje dobře, dokud soubor nemusí přečíst něco jiného než člověk, stránka, widget, souhrn emailem, a pak formát přestane být zadarmo. Automatizace changelogu pokrývá strukturální požadavek obecně, typ, datum, tělo a odkaz; tohle je o tom, který formát souboru tuhle strukturu skutečně dodává a kolik stojí se k ní dostat u každého z nich.

Co je špatně na obyčejném changelogu v Markdownu?

Nic, dokud ho něco nemusí zpětně naparsovat do polí. Nadpis, datum a odrážkový seznam pod ním je triviální přečíst pro člověka a opravdu obtížné spolehlivě naparsovat, protože Markdown nemá schéma: datum může být v nadpisu, tučně na první řádce, nebo úplně chybět u starého záznamu, a každá z těch variant je platný Markdown, který člověk čte správně a parser ne. Týmy automatizující changelog v Markdownu obvykle skončí psaním vlastního parseru založeného na regexu, který se rozbije hned první chvíli, kdy formátování záznamu byť jen mírně sklouzne, což se stává často, protože nic nevynucuje konzistenci při psaní.

Co strukturovaný formát reálně přináší?

Záruku, že každý záznam má stejný tvar, ověřenou, když je záznam napsán, místo hádanou, když je čtený. Soubor JSON nebo YAML s definovaným schématem, typ, datum, verze, publikum, tělo, odkaz, selže hlasitě, pokud chybí povinné pole, přesně jako by to udělala striktní odpověď API; soubor Markdown prostě vyrenderuje, co tam je, správně nebo ne. Ten rozdíl je neviditelný až do dne, kdy skript potřebuje datum každého záznamu, aby seřadil feed, a polovina záznamů ho má na jiném místě.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Znamená to, že soubor čitelný pro člověka musí zmizet?

Ne, a snaha nechat soubor YAML nebo JSON sloužit zároveň jako to, co člověk čte v pull requestu, je obvykle chyba opačným směrem: revidovat diff vnořeného JSONu je horší než revidovat větu prózy, a recenzentka, která musí mentálně naparsovat datovou strukturu, aby zachytila chybu formulace, je recenzentka, která nakonec přestane chyby formulace zachytávat. Oba formáty mohou koexistovat: strukturovaná data jsou zdroj pravdy, který čte automatizační pipeline, a vygenerované renderování v Markdownu nebo HTML je to, co člověk skutečně recenzuje a čte, produkované ze strukturovaného souboru místo udržované ručně vedle.

Který strukturovaný formát je reálně snazší ručně upravovat, JSON nebo YAML?

YAML, pro každého, kdo píše záznamy ručně místo přes generátor, protože odstraňuje uvozování a párování závorek, které JSON vyžaduje pro každý string a vnořený objekt. Kompromis je, že citlivost YAML na mezery selže tiše způsobem, jakým neshody závorek v JSON obvykle neselžou: parser JSON rovnou odmítne špatně formovaný vstup, zatímco parser YAML může přijmout špatně odsazený soubor a prostě ho naparsovat do špatné struktury, což je horší selhání, protože nic vám neřekne, že se to stalo. Pokud záznamy vždy píše jen skript, tenhle kompromis z velké části zmizí a přísnější parsování JSON se stane bezpečnější výchozí volbou.

Potřebuje changelog stránka vlastní strukturovaný formát, oddělený od souboru, který ji krmí?

Ne oddělený, ten samý, jinak vyrenderovaný. Changelog stránka pokrývá, jak udělat samotnou stránku strojově čitelnou přes JSON feed a schema.org markup; ten feed je vygenerovaný výstup, ne druhý zdroj pravdy, který je třeba udržovat synchronizovaný s podkladovým souborem. Ruční udržování strukturovaných dat na dvou místech, zdrojovém souboru a feedu stránky, je to, jak se ty dva nakonec rozejdou, takže rozhodnutí o formátu souboru učiněné tady by mělo být tou jedinou věcí, ze které se generuje vše po proudu, stránka, widget, email, nikdy ručně kopírované.

Vyplatí se náklad na migraci existujícího changelogu v Markdownu do strukturovaného formátu?

Obvykle jen jakmile je automatizace skutečným cílem, ne dřív. Projekt jedné osoby publikující soubor Markdown do README na GitHubu nemá reálnou potřebu automatizace, a jeho převod na YAML nekoupí nic než ceremonii. Konverze se sama zaplatí ve chvíli, kdy víc než jeden konzument po proudu, stránka, souhrnný email, veřejný feed, potřebuje číst stejná data, protože to je přesně ten bod, kde nekonzistence parseru Markdown začnou produkovat viditelně špatný výstup místo toho, aby byly jen otravné na údržbu.

FAQ

Dá se changelog v Markdownu udělat parsovatelný bez úplné změny formátu? Částečně, s frontmatterem: malý blok YAML na začátku každého záznamu (datum, typ, verze) vedle těla v Markdownu pro prózu. Tohle získá strukturovaná pole, která parser potřebuje, aniž by nutilo celý záznam do JSON nebo YAML, a je to rozumný střed pro tým ještě nepřipravený na plnou migraci.

Záleží na formátu souboru pro SEO nebo na tom, jak se changelog stránka řadí? Ne přímo. Vyhledávače čtou vyrenderovanou stránku, ne zdrojový soubor, takže formát souboru je pro ně neviditelný; na samotné stránce záleží, jestli je strojově čitelná sama o sobě, což je oddělená otázka od toho, co ji generuje.

Měl by každý záznam changelogu procházet stejným souborem, nebo se typy dají rozdělit na víc souborů? Jeden soubor je jednodušší, dokud ho objem záznamů neudělá nepohodlným na diffování nebo recenzování; rozdělení podle roku nebo kategorie je rozumný pojistný ventil, jakmile diffy jednoho souboru zvětší tak, že se nedají rozumně recenzovat, ale přidává to krok sloučení, než cokoli po proudu může přečíst “všechny záznamy” jako jeden seznam.

Existuje standardní formát souboru changelogu, jako existuje standard pro RSS? Ne široce přijatý. Keep a Changelog navrhuje konvenci Markdown, a několik nástrojů má vlastní; changeset je soubor Markdown s frontmatterem YAML, který uvádí balíček a typ zvýšení verze, což je vzor s frontmatterem popsaný výše. Žádný z nich není formát, který jiné nástroje čtou rovnou tak, jak čtečky RSS univerzálně rozumí RSS.

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: Srovnání nástrojů pro changelog, Generátor changelogu