Changelogy v monorepu: jeden, nebo jeden na balíček?

Monorepo hostí několik samostatně nasazovaných věcí v jednom repozitáři, a changelog musí nejdřív zodpovědět otázku: zajímá čtenáře repo, nebo ho zajímá konkrétní balíček uvnitř? Většina týmů se tohle nikdy nerozhodne vědomě. Začnou s jedním changelogem, protože existuje jedno repo, časem přidávají balíčky, a skončí s logem, kde uživatel CLI musí projíždět čtyřicet nesouvisejících záznamů backendu, aby našel ten, který vydal jeho opravu. Co určuje správný tvar, není struktura repozitáře, ale kdo log čte a co už ví, že hledá.

Co dělá changelog monorepa jiným než changelog jednoho repa?

Changelog jednoho repa má implicitní publikum: všechny, kdo používají tu jedinou věc, kterou to repo staví. Publikum monorepa se dělí podle balíčku, a balíčky ve stejném repu se často vydávají podle jiných harmonogramů, jiným spotřebitelům, na jiných úrovních stability. Knihovna publikovaná v registru a interní administrační nástroj mohou žít ve stejném monorepu a mít pro čtenáře changelogu téměř nic společného.

Potřebuje každý balíček vlastní changelog?

Jen ty s nezávislým publikem. Balíček publikovaný v registru potřebuje vlastní log, protože kdo ho instaluje, nemá důvod číst cokoli jiného v repu, a nástroje pro vydávání v monorepu jako Lerna a Changesets zapisují CHANGELOG.md pro každý balíček, vedle jeho package.json. Interní utilita s jedním spotřebitelem, aplikací už žijící ve stejném repu, nepotřebuje samostatný log; zahrnutí jejích změn do záznamů té aplikace je užitečnější než druhý soubor, který nikdo mimo tým neotevře.

Test je stejný, který rozhoduje, jestli nějaký záznam vůbec patří do changelogu: všiml by si toho čtenář nebo by ho to zajímalo, a může na základě toho jednat. Aplikuj to na balíček, ne na složku, a repo s dvanácti balíčky může skončit se dvěma skutečnými changelogy a deseti balíčky, které ho prostě nepotřebují.

Jak se pozná, který balíček způsobil který záznam changelogu?

Označuj každý záznam jeho balíčkem v momentě, kdy je napsán, ne dodatečně zkoumáním, jaké soubory commit ovlivnil. Commit opravující sdílenou interní knihovnu může vytvořit záznam changelogu v každém balíčku, který na ní závisí, a samotné cesty souborů nemohou říct, který z těchto navazujících záznamů čtenář opravdu potřebuje vidět; to může rozhodnout jen člověk, který určí “tohle je viditelné uživateli balíčku A a ne uživateli balíčku B”. Conventional commits tady pomáhají mechanicky, pojmenováním balíčku v každém commitu, ale scope pořád vytvoří jen koncept. Stejné dvouvrstvé pravidlo z toho článku platí na balíček: koncept se správným scope pořád potřebuje lidský průchod, než je zformulován pro skutečného čtenáře toho balíčku.

Co potřebuje sdílený changelog, co changelog jednoho repa nepotřebuje?

Štítek balíčku na každém záznamu, hned na začátku, před popisem, aby čtenář procházející log mohl jedním průchodem přeskočit všechno, co není jeho. Bez toho štítku se sdílený log čte jako náhodný feed, a čtenář zajímající se o jeden balíček ho nemá jak filtrovat, kromě zapamatování, které řádky se počítají, což po prvním týdnu nedělá nikdo.

## 2026-09-07

### [cli] Přidáno
- `acme push --dry-run` ukáže, co by se odeslalo, aniž by
  to skutečně odeslal.

### [core] Opraveno
- Backoff opakovaných pokusů se už neresetuje při úspěšném
  požadavku, který vrátí prázdné tělo.

Dva záznamy, dvě publika, jeden pohled na jejich rozlišení. Workflow ve stylu Changesets zabudovává toto značení přímo do release procesu: přispěvatel napíše krátkou poznámku, se scope balíčku, vedle své změny, a nástroj poskládá changelogy podle balíčku a skoky verzí z těchto poznámek v momentě release, místo aby se snažil rekonstruovat hranice balíčků dodatečně ze sloučené historie commitů.

Jak souvisí verzování s changelogem monorepa?

Nezávisle verzované balíčky potřebují vlastní changelog, protože mají vlastní číslo verze, a sdílený changelog nemůže vyjádřit “balíček A přešel z 2.1 na 2.2, zatímco balíček B zůstal na 1.4”, aniž by se stal dvěma logy v jednom souboru. Semantic versioning a váš changelog pokrývá, jak by se číslo verze mělo mapovat na kategorie changelogu; v monorepu je potřeba to mapování aplikovat na balíček, protože breaking change v jednom balíčku není breaking change pro sesterský balíček, který na něm nezávisí.

Repo, které vydává jeden produkt jako jednu nasazovanou jednotku, i když je postavené z mnoha interních balíčků, tenhle problém nemá: balíčky sdílí verzi, protože se vždy vydávají spolu, a jeden changelog je správně.

Jak zapadají git tagy do monorepa?

Stejné pravidlo z git tagů, releasů a vašeho changelogu platí, aplikované na balíček: balíček s vlastní verzí potřebuje vlastní prefix tagu, typicky nazev-balicku@1.4.0 místo holého v1.4.0, který nemůže říct, ke kterému balíčku patří. Monorepo otagované jen holými čísly verzí nemůže později odpovědět “co bylo v core, když cli vydal 2.2”, protože nic na disku nezaznamenává, ke kterému balíčku ten tag skutečně patřil.

FAQ

Potřebuji samostatný changelog pro každý balíček v monorepu? Jen pro balíčky s nezávislým publikem, obvykle cokoli publikované v registru. Balíček s jedním interním spotřebitelem už žijícím ve stejném repu se může začlenit do logu toho spotřebitele místo udržování vlastního.

Co označuje záznam changelogu správným balíčkem? Osoba, která záznam píše, v momentě, kdy ho píše, ne automatické skenování změněných cest souborů. Změna ve sdílené knihovně může vytvořit jiný záznam v každém závislém balíčku, a jen člověk může rozhodnout, co by měl každý z těch navazujících záznamů skutečně říkat.

Mělo by monorepo používat jedno číslo verze pro všechno? Jen pokud se každý balíček vždy vydává spolu s ostatními. Pokud jsou balíčky někdy publikovány nezávisle, potřebují nezávislé verze, a nezávislé verze potřebují nezávislé changelogy, aby dávaly smysl.

Nahrazuje nástroj na changelog monorepa krok lidské editace? Ne. Nástroje jako Changesets automatizují sběr a skládání poznámek podle balíčku v momentě release; samotná poznámka, napsaná jazykem čtenáře místo přispěvatele, zůstává prací člověka, stejně jako v jakémkoli jiném pipeline changelogu.

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