Keep a Changelog, naprawdę wdrożony

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:

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.

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.

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.

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.

Powiązane w changeloop: Przykłady changeloga, Porównanie narzędzi do changeloga