Changelog: co to jest? Z przykładowym wpisem

Changelog to datowany zapis tego, co zmieniło się w produkcie, napisany dla osób, których dotyczy zmiana, nie dla zespołu, który ją wydał. Każdy wpis nazywa zmianę, mówi, kiedy weszła w życie, i mówi, co czytelniczka powinna z tym zrobić, co w większości wpisów oznacza nic. To właśnie ta ostatnia część odróżnia changelog od logu commitów: log commitów to zapis dla tych, którzy napisali kod, changelog to zapis dla tych, którzy go używają.

Czym jest changelog, dokładnie?

Lista datowanych wpisów, od najnowszego, każdy opisuje pojedynczą zmianę w kategoriach, które czytelniczka może sprawdzić. Nie to, co zbudował zespół, ale to, co jest teraz inne. “Refaktoryzacja usługi rozliczeniowej” to komunikat commita. “Faktury pokazują teraz podatek jako osobną linię” to wpis w changelogu, bo mówi czytelniczce coś, co może zweryfikować na własnym koncie.

Format jest stary i celowo prosty: nagłówek na wydanie lub dzień, krótka lista poniżej, czasem etykieta kategorii. Keep a Changelog to najczęściej cytowana specyfikacja tej formy, i istnieje, bo większość projektów pomijających specyfikację kończy zrzucaniem historii commitów w zamian, co odpowiada na inne pytanie niż to, z którym przyszła czytelniczka.

Ta piątka nakłada się w praktyce, ale to nie ten sam dokument, a różnica leży w tym, kto go trzyma w chwili czytania. Changelog jest zbudowany do wyszukiwania i późniejszego linkowania, dlatego jego wpisy bardziej niż inne potrzebują dat i stabilnych adresów URL.

Co naprawdę zawiera wpis w changelogu?

Cztery rzeczy, w tej kolejności: co się zmieniło, ujęte w kategoriach, które zauważyłaby użytkowniczka lub wywołujący; kiedy weszło w życie; do jakiej kategorii należy (added, fixed, changed, removed to cztery powszechne); i, gdy ma to znaczenie, co czytelniczka powinna z tym zrobić. Link do dalszych szczegółów jest mile widziany. Akapit wewnętrznego uzasadnienia nie, bo czytelniczka nie pytała dlaczego, pytała co.

## 2026-09-07

### Added
- Faktury pokazują teraz podatek jako osobną linię, w walucie konta
  klienta.

### Fixed
- Eksport raportu jako CSV nie usuwa już ostatniego wiersza, gdy raport
  przekracza 10 000 wierszy.

Ta forma skaluje się od aktualizacji o dwóch liniach do stu wpisów w jednym wydaniu bez zmiany struktury, i to jest prawdziwy test tego, czy format działa: czy czyta się tak samo w pracowitym tygodniu, jak w spokojnym.

Kto pisze changelog, i kiedy?

Ta, która wprowadziła zmianę, w momencie wydania, nie techniczna redaktorka rekonstruująca ją z ticketów tydzień później. Ta, która dotknęła kodu, wie, co naprawdę zmieniło się dla użytkowniczki; podsumowanie napisane później ma tendencję do opisywania ticketu zamiast tego, co faktycznie wydano, a to zwykle jest szersze lub węższe niż rzeczywisty zakres. Niektóre zespoły dodają etap przeglądu przed publikacją wpisu, głównie żeby wyłapać wewnętrzny język, który się wkradł, i ten przegląd powinien być wystarczająco szybki, żeby wpis wyszedł tego samego dnia.

Gdzie powinien być changelog?

Na własnej stronie, pod stabilnym adresem URL, dystrybuowany jako feed. Zakopany w menu ustawień lub tagu wydania na hoście kodu, dociera tylko do tych, które już wiedziały, gdzie szukać. Publiczną stronę można linkować z ticketu wsparcia, cytować w recenzji, lub subskrybować. Feed liczy się tak samo jak strona: czytelniczka, która sprawdza changelog produktu raz w miesiącu, jest rzadkością, ta, która go subskrybuje, nie jest, i tylko feed obsługuje drugą grupę.

Czym różni się od notatek wydania?

Te dwa są nieustannie mylone, i różnią się wystarczająco, żeby ich mieszanie dawało dokument, który dobrze nie służy żadnej z dwóch czytelniczek. Changelog kontra notatki wydania przechodzi przez to rozróżnienie w całości; krótko mówiąc, changelog to pełny, chronologiczny zapis, a notatki wydania to wyselekcjonowany podzbiór, napisany tak, żeby aktualizacja brzmiała warto mieć. Produkt zwykle potrzebuje obu, skierowanych do różnych momentów dnia czytelniczki.

Co sprawia, że changelog jest wart przeczytania?

Konkretność i uczciwość co do własnego zakresu. “Różne poprawki błędów” to zdanie, które uczy czytelniczkę przestać otwierać stronę, bo nie obiecuje niczego, co mogłaby zweryfikować. Wpis, który nazywa dokładne zachowanie, które się zmieniło, nawet przy małej poprawce, jest tym, który utrzymuje subskrypcję przy życiu. Ta dyscyplina dotyczy też tego, co się pomija: changelog, który ogłasza tylko sukcesy i nigdy poprawkę czegoś, co było zepsute, czyta się jak marketing przebrany za changelog, i czytelniczki to zauważają.

Dyscyplina wersjonowania też się liczy. Semantic versioning a twój changelog pokazuje, jak numer wersji i wpis powinny się zgadzać, żeby czytelniczka przeglądająca historię wersji dostawała ten sam sygnał dwa razy zamiast dwóch różnych.

Jak powstają changelogi?

Na dwa sposoby, i większość rzeczywistych konfiguracji to mieszanka. Generowanie automatyczne czyta komunikaty commitów, zwykle w formacie Conventional Commits, i zamienia je we wpisy bez dotykania wyniku przez nikogo; od conventional commits do changeloga opisuje ten pipeline. Generowanie wyselekcjonowane oznacza, że ktoś ręcznie pisze lub edytuje każdy wpis. Wynik automatyczny jest szybszy i nigdy nie przegapia scalonego pull requesta, ale dziedziczy każdy niejasny komunikat commita dosłownie, więc większość zespołów, które automatyzują, i tak zachowuje lekki przegląd przed publikacją zamiast pokazywać surowy wynik.

FAQ

Czy każdy produkt potrzebuje changeloga? Każdy produkt z użytkowniczkami dotkniętymi zmianą go potrzebuje, niezależnie czy to aplikacja SaaS, wewnętrzne narzędzie, czy publiczne API. Forma się dostosowuje (changelog API czyta się inaczej niż aplikacji konsumenckiej), potrzeba nie.

Czym jest changelog w kategoriach oprogramowania? Ta sama definicja co powyżej: datowana, chronologiczna lista tego, co zmieniło się w oprogramowaniu, napisana dla tych, którzy go używają, nie dla tych, którzy go zbudowali.

Czy changelog może być generowany automatycznie z commitów? Tak, i wiele zespołów robi dokładnie to, zwykle z komunikatów w formacie Conventional Commits. Kompromis polega na tym, że wygenerowany wpis jest tak jasny, jak komunikat commita, z którego pochodzi, więc przegląd przed publikacją wyłapuje te wymagające przeredagowania.

Czy changelog to to samo co historia wersji? Wystarczająco blisko, żeby terminy były używane zamiennie. Historia wersji to czasem tylko lista numerów wersji i dat bez opisu; changelog zawsze zawiera to, co się zmieniło.

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: Przykłady changeloga, Dokumentacja dla deweloperów