Tagi git, wydania i twój changelog

Tag git, wydanie i wpis w changelogu to trzy różne zapisy tego samego zdarzenia, a mieszanie ich sprawia, że changelog cicho dryfuje od tego, co naprawdę zostało wydane. Tag oznacza commit. Wydanie pakuje ten tag z artefaktami i opisem. Wpis w changelogu wyjaśnia, w terminach, których czytelniczka spoza repozytorium może użyć, co się zmieniło. Zwykle dzieją się blisko siebie w czasie, i właśnie dlatego łatwo traktować je jako jeden krok zamiast trzech, i właśnie dlatego luka staje się widoczna dopiero miesiące później, gdy ktoś pyta „co wyszło w v2.4”, a szczera odpowiedź wymaga prawdziwego kopania.

Jaka jest rzeczywista różnica między trzema?

Tag jest najbardziej mechaniczny z trzech: git tag v2.4.0 i gotowe, bez żadnego wymogu, by coś wyjaśniało, co zawiera. Wydanie dodaje opis i zwykle artefakty do pobrania, a jego odbiorczyniami wciąż są deweloperki, które wiedzą, czym jest strona wydania. Wpis w changelogu to jedyny z trzech napisany dla czytelniczki, która może nigdy nie otworzyć repozytorium, dlatego to on wymaga najwięcej uwagi redakcyjnej i najczęściej jest pomijany pod presją terminów.

Czy każdy tag git potrzebuje wpisu w changelogu?

Nie, a traktowanie ich jeden do jednego to częsty błąd. Tag może oznaczać wewnętrzny kamień milowy, release candidate, lub hotfix, który nigdy nie dociera do większości użytkowniczek; żaden z nich niekoniecznie potrzebuje publicznego wpisu. Test jest ten sam, który decyduje, czy coś w ogóle należy do changeloga: czy użytkowniczka lub wywołująca by to zauważyła lub by ją to obchodziło. Większość tagów przechodzi ten test. Niektóre, jak tag stworzony tylko po to, by wyzwolić pipeline CI, nigdy.

Czy każdy wpis w changelogu potrzebuje własnego tagu?

Nie zawsze, i tu rozchodzą się zespoły wdrażające w sposób ciągły od zespołów wydających zwersjonowane pakiety. Produkt SaaS wdrażany kilka razy dziennie może grupować wiele wdrożeń pod jednym datowanym wpisem w changelogu bez tagu 1:1 na wdrożenie; biblioteka publikowana w rejestrze pakietów zwykle potrzebuje tagu na opublikowaną wersję. Moduły Go i Swift Package Manager rozwiązują wersje bezpośrednio z tagów; w npm czy PyPI opublikowaną wersję przechowuje rejestr, a tag pozwala każdemu przypisać tę wersję z powrotem do jej źródła. Repozytorium z kilkoma niezależnie wersjonowanymi pakietami musi zdecydować o tym na pakiet, nie raz dla całego repo; changelogi w monorepo opisuje, jak prefiksy tagów i zakres changeloga powinny podążać za granicami pakietów, nie folderów. Semantic versioning a twój changelog opisuje, jak sam numer wersji powinien mapować się na kategorie changeloga; tagi są mechanizmem, który sprawia, że numer wersji można zweryfikować względem rzeczywistego kodu.

Jak opis wydania powinien się odnosić do wpisu w changelogu?

Mogą być tym samym tekstem, ale tylko jeśli odbiorczynie obu są naprawdę takie same, co jest rzadsze, niż się wydaje. Stronę wydania na hostingu kodu czytają niemal wyłącznie deweloperki; jeśli produkt ma też nietechniczne użytkowniczki czytające changelog, dosłowne duplikowanie opisu wydania wysyła wewnętrzne terminy i sformułowania zorientowane na kod do czytelniczki, która potrzebowała wersji w prostym języku. Najczystszy wzorzec: napisać wpis w changelogu jako główny, zorientowany na czytelniczkę artefakt, i pozwolić, by opis wydania albo do niego linkował, albo zawierał krótsze, bardziej techniczne podsumowanie dla odbiorczyń, które już czują się tam swobodnie.

# Wydanie v2.4.0 (GitHub, dla deweloperek)
Podnosi pipeline raportów do nowego silnika agregacji. Zobacz
changelog po podsumowanie dla klientek:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, dla klientek)
### Added
- Raporty ładują się teraz w mniej niż sekundę, nawet dla kont z
  ponad milionem wierszy.

To samo wydanie, dwa dokumenty, każdy z własnym sformułowaniem dla własnej czytelniczki.

Skąd faktycznie bierze się wpis w changelogu?

Z dwóch punktów startowych, i większość rzeczywistych pipeline’ów to mieszanka obu. Może być generowany z komunikatów commitów w momencie tagowania, co jest szybkie i nigdy nie pomija scalonego pull requestu; od conventional commits do changeloga opisuje ten pipeline w całości. Albo może być napisany ręcznie, całkowicie osobno od tagu, zsynchronizowany z momentem, gdy funkcja uznawana jest za gotową, zamiast z momentem scalenia kodu. Generowane wpisy są spójne, ale dziedziczą każdy niejasny komunikat commita; ręcznie pisane wpisy są jaśniejsze, ale potrzebują kogoś, kto je faktycznie napisze. Większość zespołów, które automatyzują, i tak zachowuje lekki przebieg redakcyjny na wygenerowanym tekście, zanim stanie się publicznym wpisem, ta sama dyscyplina, którą zaleca Keep a Changelog, w praktyce, niezależnie od tego, skąd pierwotnie pochodził surowy tekst.

Co się psuje, gdy trzy wypadają z synchronizacji?

Zaufanie do tego, co czytelniczka sprawdziła pierwsze. Tag, który istnieje bez odpowiadającego mu wpisu w changelogu, wygląda, z perspektywy czytelniczki changeloga, jakby w tym tygodniu nic się nie wydarzyło. Wpis w changelogu bez odpowiadającego mu tagu lub wydania uniemożliwia komuś debugującemu problem produkcyjny checkoutowanie dokładnie tego kodu, który był na żywo, gdy wpis został opublikowany. Rozwiązaniem nie jest doskonała automatyzacja, tylko jedno źródło prawdy dla tego mapowania: jedno miejsce, choćby własna lista kontrolna procesu wydawania, które mówi, że możliwa do wydania zmiana dostaje wszystkie trzy, w tym samym commicie lub pull requeście, który ją wprowadza.

FAQ

Czy wpisy w changelogu powinny być generowane automatycznie z tagów git? Mogą być punktem startowym, ale sam tag nie niesie żadnego opisu zorientowanego na czytelniczkę, tylko zakres commitów. Zautomatyzowana generacja musi czytać komunikaty commitów w tym zakresie, nie tylko istnienie tagu, żeby wyprodukować coś użytecznego.

A jeśli nie tagujemy każdego wydania? Wtedy wpis w changelogu staje się głównym zapisem, i powinien mimo to nieść datę oraz, jeśli produkt ją ma, numer wersji, żeby wpis pozostał czymś, do czego czytelniczka może się później odnieść, nawet bez odpowiadającego mu tagu.

Czy tagi przed wydaniem (jak v2.4.0-rc.1) powinny mieć wpisy w changelogu? Ogólnie nie. Release candidate jest do testów wewnętrznych lub beta, a wpis w changelogu dla niego uczy czytelniczki oczekiwać wpisów dla wersji, które mogą nigdy nie zostać wydane tak, jak opisano. Zachowaj wpisy dla tagów, które osiągają ogólną dostępność.

Czy jeden wpis w changelogu może obejmować wiele tagów git? Tak, i często powinien dla zespołów, które tagują często. Grupuj powiązane tagi pod jednym datowanym wpisem opisującym zmianę netto, zamiast publikować cienki wpis na tag, który fragmentuje funkcję na wiele lektur.

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