Changelogi w monorepo: jeden, czy jeden na pakiet?

Monorepo mieści kilka osobno wdrażanych rzeczy w jednym repozytorium, a changelog musi najpierw odpowiedzieć na pytanie: czy czytelnika obchodzi repo, czy obchodzi go konkretny pakiet w środku? Większość zespołów nigdy nie decyduje o tym świadomie. Zaczynają od jednego changeloga, bo jest jedno repo, dodają pakiety z czasem, i kończą z logiem, w którym ktoś używający CLI musi przewijać przez czterdzieści niepowiązanych wpisów backendu, żeby znaleźć ten, który wydał jego poprawkę. To, co decyduje o właściwej formie, to nie struktura repozytorium, tylko kto czyta log i czego już szuka.

Co odróżnia changelog monorepo od changeloga pojedynczego repo?

Changelog pojedynczego repo ma domyślnego odbiorcę: wszystkich, którzy używają jedynej rzeczy, którą to repo buduje. Odbiorcy monorepo dzielą się według pakietu, a pakiety w tym samym repo często są wydawane według różnych harmonogramów, dla różnych konsumentów, na różnych poziomach stabilności. Biblioteka publikowana w rejestrze i wewnętrzne narzędzie administracyjne mogą żyć w tym samym monorepo i nie mieć prawie nic wspólnego dla kogoś, kto czyta changelog.

Czy każdy pakiet potrzebuje własnego changeloga?

Tylko te z niezależnym odbiorcą. Pakiet publikowany w rejestrze potrzebuje własnego loga, bo osoba, która go instaluje, nie ma powodu czytać niczego innego w repo, a narzędzia do wydań w monorepo, takie jak Lerna i Changesets, zapisują CHANGELOG.md dla każdego pakietu, obok jego package.json. Wewnętrzne narzędzie z jednym konsumentem, aplikacją już żyjącą w tym samym repo, nie potrzebuje osobnego loga; włączenie jego zmian do wpisów tej aplikacji jest bardziej przydatne niż drugi plik, którego nikt spoza zespołu nie otwiera.

Test jest ten sam, który decyduje, czy jakikolwiek wpis należy do changeloga: czy czytelnik by to zauważył albo się tym przejął, i czy może na tej podstawie działać. Zastosuj go na pakiet, nie na folder, a repo z dwunastoma pakietami może skończyć z dwoma prawdziwymi changelogami i pakietami, które po prostu tego nie potrzebują.

Skąd wiadomo, który pakiet spowodował który wpis w changelogu?

Etykietuj każdy wpis jego pakietem w momencie, gdy jest pisany, nie później, sprawdzając, jakie pliki dotknął commit. Commit naprawiający wspólną wewnętrzną bibliotekę może wytworzyć wpis changeloga w każdym pakiecie, który od niej zależy, a same ścieżki plików nie mogą powiedzieć, który z tych wpisów pochodnych czytelnik naprawdę musi zobaczyć; może to zrobić tylko osoba decydująca “to jest widoczne dla użytkownika pakietu A, a nie dla użytkownika pakietu B”. Conventional commits pomagają tu mechanicznie, nazywając pakiet w każdym commicie, ale scope wciąż tworzy tylko szkic. Ta sama dwuwarstwowa zasada z tego artykułu obowiązuje na pakiet: szkic z właściwym scope wciąż potrzebuje ludzkiego przejścia, zanim zostanie sformułowany dla prawdziwego czytelnika tego pakietu.

Czego potrzebuje wspólny changelog, czego nie potrzebuje changelog pojedynczego repo?

Etykiety pakietu przy każdym wpisie, na samym początku, przed opisem, żeby czytelnik przeglądający log mógł jednym przejściem pominąć wszystko, co nie jest jego. Bez tej etykiety wspólny log czyta się jak przypadkowy feed, a czytelnik zainteresowany jednym pakietem nie ma jak go filtrować poza zapamiętywaniem, które linie się liczą, czego nikt nie robi po pierwszym tygodniu.

## 2026-09-07

### [cli] Dodano
- `acme push --dry-run` pokazuje, co zostałoby wysłane, bez
  faktycznego wysyłania.

### [core] Naprawiono
- Backoff ponownych prób nie resetuje się już przy udanym
  żądaniu, które zwraca pusty body.

Dwa wpisy, dwaj odbiorcy, jedno spojrzenie, żeby je rozróżnić. Przepływ pracy w stylu Changesets wbudowuje to etykietowanie bezpośrednio w proces wydania: kontrybutor pisze krótką notatkę, ze scope pakietu, obok swojej zmiany, a narzędzie składa changelogi na pakiet i skoki wersji z tych notatek w momencie wydania, zamiast próbować odtworzyć granice pakietów po fakcie z połączonej historii commitów.

Jak wersjonowanie łączy się z changelogiem monorepo?

Niezależnie wersjonowane pakiety potrzebują własnego changeloga, bo mają własny numer wersji, a wspólny changelog nie może wyrazić “pakiet A przeszedł z 2.1 na 2.2, podczas gdy pakiet B został na 1.4” bez stania się dwoma logami w jednym pliku. Semantic versioning a twój changelog opisuje, jak numer wersji powinien mapować się na kategorie changeloga; w monorepo to mapowanie trzeba zastosować na pakiet, bo zmiana łamiąca w jednym pakiecie nie jest zmianą łamiącą dla pakietu siostrzanego, który od niego nie zależy.

Repo, które wydaje jeden produkt jako jedną wdrażaną jednostkę, nawet jeśli zbudowaną z wielu wewnętrznych pakietów, nie ma tego problemu: pakiety dzielą wersję, bo zawsze są wydawane razem, i jeden changelog jest właściwy.

Jak tagi git pasują do monorepo?

Ta sama zasada z tagów git, wydań i twojego changeloga obowiązuje, zastosowana na pakiet: pakiet z własną wersją potrzebuje własnego prefiksu tagu, zwykle nazwa-pakietu@1.4.0 zamiast gołego v1.4.0, który nie może powiedzieć, do którego pakietu należy. Monorepo otagowane tylko gołymi numerami wersji nie może później odpowiedzieć “co było w core, gdy cli wydał 2.2”, bo nic na dysku nie zapisuje, do którego pakietu ten tag faktycznie należał.

FAQ

Czy potrzebuję osobnego changeloga dla każdego pakietu w monorepo? Tylko dla pakietów z niezależnym odbiorcą, zwykle wszystkiego publikowanego w rejestrze. Pakiet z jednym wewnętrznym konsumentem już żyjącym w tym samym repo może wejść do loga tego konsumenta zamiast utrzymywać własny.

Co etykietuje wpis changeloga właściwym pakietem? Osoba pisząca wpis, w momencie, gdy go pisze, nie automatyczne skanowanie zmienionych ścieżek plików. Zmiana we wspólnej bibliotece może wytworzyć inny wpis w każdym pakiecie, który od niej zależy, i tylko człowiek może zdecydować, co każdy z tych wpisów pochodnych naprawdę powinien mówić.

Czy monorepo powinno używać jednego numeru wersji dla wszystkiego? Tylko jeśli każdy pakiet jest zawsze wydawany razem z resztą. Jeśli pakiety kiedykolwiek są publikowane niezależnie, potrzebują niezależnych wersji, a niezależne wersje potrzebują niezależnych changelogów, żeby miały sens.

Czy narzędzie do changeloga monorepo zastępuje ludzki krok edycji? Nie. Narzędzia jak Changesets automatyzują zbieranie i składanie notatek na pakiet w momencie wydania; sama notatka, napisana językiem czytelnika zamiast kontrybutora, wciąż jest pracą człowieka, tak jak w każdym innym pipeline changeloga.

Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.

Powiązane w changeloop: Generator changeloga, Dokumentacja dla deweloperów