Keep a Changelog: wyjaśnienie i szablon CHANGELOG.md
5 min czytania zaktualizowano
Keep a Changelog to jednostronicowa konwencja dla CHANGELOG.md: najnowsza wersja pierwsza,
jedna sekcja na wersję z numerem i datą ISO, wpisy pogrupowane pod sześcioma typami (Added,
Changed, Deprecated, Removed, Fixed, Security), i sekcja Unreleased na górze dla wpisów między
wydaniami. Większość zespołów, które ją cytują, wdraża około dwie trzecie z niej, a jedna trzecia,
którą pomijają, to ta, która chroni ich użytkowników.
Olivier Lacan opublikował Keep a Changelog w 2014 roku ze zdaniem, które postarzało się lepiej niż większość prozy o oprogramowaniu: don’t let your friends dump git logs into changelogs. Dziesięć lat później to najbliższe standardowi, co ma ten zakątek oprogramowania. Warto przeczytać źródło zamiast streszczenia; ten tekst dotyczy części, które są pomijane.
O co prosi Keep a Changelog?
CHANGELOG.md w katalogu głównym repo, najnowsza wersja pierwsza, z jedną sekcją na wersję.
Każda wersja niesie numer i datę ISO, i grupuje swoje wpisy pod sześcioma typami:
| Typ | Dla | Koszt jego pominięcia |
|---|---|---|
| Added | Nowe funkcje | Nic; nikt tego nie pomija |
| Changed | Zmiany w istniejącym zachowaniu | Czytelnicy dowiadują się o zmianie zachowania z błędu |
| Deprecated | Funkcje, które zostaną usunięte | Usunięcie staje się incydentem zamiast zaplanowanym wydarzeniem |
| Removed | Funkcje usunięte w tym wydaniu | Nikt nie odróżnia usunięcia od błędu |
| Fixed | Poprawki błędów | Nic; nikt tego też nie pomija |
| Security | Podatności | Jedyna czytelniczka, która ich szukała, ich nie znajduje |
Plus sekcja Unreleased na górze, żeby było miejsce na wpis w chwili, gdy jest zmergowany, i żeby
każdy mógł zobaczyć, co nadchodzi.
To prawie wszystko. Reszta to uzasadnienie: wpisy są dla ludzi, jeden wpis na zmianę, a plik to dokument, a nie log.
Jak wygląda plik Keep a Changelog?
Oto kompletny CHANGELOG.md w tej formie: sekcja Unreleased, dwie wydane wersje z datami ISO,
wszystkie sześć typów i linki porównawcze na dole, które czynią każdy nagłówek wersji klikalnym.
Nagłówki zostają po angielsku w każdym języku, tak jak zapisuje je specyfikacja; wpisy piszecie w
języku, którego używają wasi czytelnicy.
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog][kac],
and this project adheres to [Semantic Versioning][semver].
## [Unreleased]
### Added
- Eksport dowolnego raportu do CSV ze strony raportów.
## [1.1.0] - 2026-10-02
### Added
- Webhooki dla zdarzeń faktur.
### Changed
- Strony raportów ładują najpierw 50 najnowszych wierszy zamiast
wszystkich.
### Deprecated
- `GET /v1/export` przestaje działać 2026-12-01.
Użyj zamiast tego `GET /v2/exports`.
### Removed
- Eksport XML. Użyj zamiast niego eksportu CSV.
### Fixed
- Konta zwolnione z podatku nie widzą już zerowej linii podatku
na fakturach.
### Security
- Ciasteczka sesji są teraz wysyłane z `SameSite=Lax`.
## [1.0.0] - 2026-08-14
### Added
- Pierwsze publiczne wydanie.
[kac]: https://keepachangelog.com/en/1.1.0/
[semver]: https://semver.org/spec/v2.0.0.html
[unreleased]: https://github.com/acme/app/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/acme/app/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/acme/app/releases/tag/v1.0.0
Które części Keep a Changelog są pomijane?
Sekcja Unreleased, potem cztery z sześciu typów, wśród nich Security, w tej kolejności.
Unreleased znika pierwsza. To sekcja bez terminu, więc to ta, której utrzymanie kończy się
pierwsze, a gdy zniknie, wpisy są pisane w momencie wydania z historii commitów. To dokładnie
zrzut git-loga, przed którym specyfikacja ostrzega już na początku, osiągnięty stopniowo.
Automatyzacja changelogu w większości dotyczy utrzymania tej
sekcji przy życiu bez konieczności pamiętania o tym przez kogokolwiek.
Sześć typów zapada się do dwóch. Większość prawdziwych changelogów kończy z Added i Fixed, ponieważ Changed i Deprecated wymagają osądu, na czym ktoś polegał. Ten osąd to wartościowa część. Deprecated w szczególności to jedyny typ będący obietnicą na przyszłość, a jego pominięcie to sposób, w jaki usunięcie zmienia się w incydent; mechanikę dotrzymania tej obietnicy opisuje jak deprecjonować API.
Security przestaje być oddzielny. Poprawka bezpieczeństwa umieszczona pod Fixed jest niewidoczna dla jedynej czytelniczki, która jej szukała. Zachowaj ją oddzielnie, nawet gdy poprawka jest trywialna, a zwłaszcza gdy wolelibyście nie zwracać na nią uwagi.
Czego nie odpowiada specyfikacja?
To format pliku. Nie mówi nic o pytaniach, na które natraficie od razu po jej przyjęciu:
- Jak ktoś się o tym dowiaduje? Plik w repo dociera do współtwórców. Nie dociera do klientki, która nigdy nie otworzyła GitHuba.
- A produkty bez wersji? Ciągle wdrażana usługa nie ma v4.2.0, według której można grupować. Większość zespołów zastępuje to datami, co działa, a specyfikacja tego ani nie błogosławi, ani nie zabrania.
- Kto pisze wpis? Specyfikacja zakłada, że robi to człowiek. Nie mówi kiedy.
- A wielu odbiorców? Jeden plik obsługuje deweloperów. Nie dostarcza tej samej treści nietechnicznej administratorce, a ręczne przeformatowanie dla niej to miejsce, gdzie zaczyna się duplikacja. Changelog vs release notes to podział, który specyfikacja zostawia wam do samodzielnego zrobienia.
Common Changelog, bardziej rygorystyczna odmiana tej idei, zaostrza część tego: zabrania pewnych sformułowań wpisów, wymaga linku do zmiany, i ma zdecydowaną opinię o tym, kim jest czytelnik. Warto przeczytać, jeśli luźne części Keep a Changelog to to, o czym wasz zespół nieustannie się spiera.
Czy Keep a Changelog można zautomatyzować bez zrzucania git logów?
Tak: wyprowadźcie szkic ze strukturalnych commitów, umieśćcie go w Unreleased z wstępnie wypełnionym typem, i wymagajcie, by człowiek edytował sformułowanie przed cięciem wydania. Ostrzeżenie specyfikacji dotyczy wyniku, nie narzędzia. Wyprowadzenie szkicu z commitów jest w porządku. Publikowanie tego szkicu bez edycji jest tym, czemu się sprzeciwia.
Maszyna zajmuje się zbieraniem i formatowaniem, w czym jest dobra. Człowiek zajmuje się selekcją i sformułowaniem, w czym nie jest. Conventional commits opisuje dwuwarstwowy podział, na którym to się opiera, i to, które typy commitów mapują się na które z sześciu powyższych kategorii. Nasze zestawienie narzędzia do changelogu obejmuje to, co istnieje dla połowy zbierania, a darmowy generator changelogu zamienia wklejony log commitów w pogrupowany szkic, który możecie edytować, zanim trafi do Unreleased.
Gdzie Keep a Changelog przestaje wystarczać?
Kończy się na dystrybucji. Keep a Changelog to dobra odpowiedź na “jak powinien wyglądać ten plik”. To nie odpowiedź na “jak nasi użytkownicy dowiadują się, co się zmieniło”, ponieważ plik Markdown w repo to strategia dystrybucji, która działa tylko, gdy wasi użytkownicy są współtwórcami.
To przeszkoda, na którą większość zespołów trafia jako drugą: plik jest w porządku, a nikt poza zespołem go nie czyta. Rozwiązanie tego oznacza, że wpisy muszą stać się danymi, które można renderować gdzie indziej, co jest innym problemem niż formatowanie pliku, i powodem, dla którego przykłady changelogu zbiera publiczne strony changelogów zamiast plików repozytorium. Jak zmienić te wpisy w coś, do czego ludzie wracają, omawia jak zbudować stronę changeloga.
Mimo to przyjmijcie specyfikację. Kosztuje popołudnie, czyni drugi problem możliwym do opanowania, i wciąż jest najlepszą stroną, jaką kiedykolwiek na ten temat napisano. Kompletny plik ułożony według niej jest w CHANGELOG.md: co w nim jest.
FAQ
Czy Keep a Changelog to standard? To szeroko przyjęta konwencja, nie specyfikacja organu normalizacyjnego. Narzędzia (skrypty wydań, lintery, parsery) na tyle często zakładają jego formę, że przestrzeganie go kupuje kompatybilność.
Co trafia do sekcji Unreleased? Każdy wpis dla zmiany, która została zmergowana, ale jeszcze nie wydana w numerowanym wydaniu. Gdy wydanie jest cięte, sekcja zostaje przemianowana na wersję i datę, a nowa, pusta sekcja Unreleased trafia nad nią.
Czy changelog powinien używać wersjonowania semantycznego? Keep a Changelog to zaleca i nie wymaga. Biblioteki i API na tym korzystają; ciągle wdrażana usługa zwykle zastępuje to datami, na co format pozwala.
Czy poprawki bezpieczeństwa powinny być w changelogu, zanim staną się publiczne? Dodajcie wpis, gdy poprawka jest wydana, z wystarczającym szczegółem, by operatorka mogła działać, i nie więcej. Opóźnianie wpisu do daty skoordynowanego ujawnienia jest normalne; pomijanie go nie jest.
Twierdzenia techniczne w tym artykule nie zostały niezależnie zweryfikowane. Jeśli coś się nie zgadza, daj nam znać, a poprawimy to.