Changelog vs release notes: jaka jest różnica?

Changelog to ciągły, kumulatywny rejestr wszystkiego, co się zmieniło, napisany dla kogoś, kto czegoś szuka. Release notes to wyselekcjonowana wiadomość o jednym wydaniu, napisana dla kogoś, kto decyduje, czy go to obchodzi. Różnica dotyczy odbiorcy, nie formatowania, i większość zespołów potrzebuje obu: jednego jako odniesienia, drugiego jako ogłoszenia, wyprowadzonych z tych samych wpisów.

Większość zespołów kończy z jednym przez przypadek, a drugim na życzenie. Zaczynacie od changelogu, bo deweloperka chce rejestru tego, co zostało wydane. Miesiące później ktoś ze wsparcia pyta, dlaczego klienci nie wiedzieli o funkcji działającej od kwietnia, i teraz potrzebujecie release notes.

Changelog vs release notes, obok siebie

Czym jest changelog?

Changelog to chronologiczny, niemal kompletny rejestr tego, co się zmieniło, od najnowszego, z każdym wpisem otypowanym (added, changed, deprecated, removed, fixed, security) i datowanym. Jego czytelnik już zdecydował, że go to obchodzi. Czegoś szuka: kiedy zmieniło się zachowanie, czy błąd jest naprawiony, która wersja wprowadziła flagę. Kompletność to cała wartość, dlatego konwencja Keep a Changelog poświęca większość swojej jednej strony na strukturę, a prawie nic na prozę.

Czym są release notes?

Release notes to selektywna wiadomość, napisana prozą, o jednym wydaniu. Jej czytelnik jeszcze nic nie zdecydował. Decyduje, czy to wydanie go dotyczy, i czy musi coś w związku z tym zrobić. Selekcja to cała wartość: release note, która wymienia wszystko, jest changelogiem z akapitami, i zawodzi czytelnika w ten sam sposób, w jaki zawodzi swojego czytelnika changelog pomijający rzeczy. Jak pisać release notes dotyczy selekcji i sformułowań.

Czy potrzebujesz zarówno changelogu, jak i release notes?

Potrzebujecie obu, gdy wasi dwaj odbiorcy zaczynają chcieć różnych rzeczy; do tego czasu jeden artefakt wykonujący obie prace jest właściwy. Małe zespoły publikują jedną stronę /changelog z krótkim akapitem na górze każdego wpisu, i przez jakiś czas służy to równie dobrze deweloperce szukającej poprawki, jak i klientce przeglądającej nowości. Dzielenie zbyt wcześnie daje wam dwie rzeczy do utrzymania, a jedna z nich zgnije.

Podział staje się wart wysiłku, gdy zaczyna się to dziać:

• Wasze wpisy changelogu urosły w wyjaśniające akapity, które deweloperzy pomijają.
• Albo odwrotnie: wasze ogłoszenia wydań zaczęły wymieniać aktualizacje zależności.
• Wsparcie kopiuje wpisy do e-maili i przepisuje je po drodze.
• Ktoś prosi o “tylko zmiany łamiące kompatybilność”, a wy nie możecie ich odfiltrować.

Ta ostatnia to prawdziwy sygnał. Jeśli nikt nie może odpowiedzieć “co się zmieniło, co mnie dotyczy” bez przeczytania wszystkiego, macie jeden artefakt wykonujący dwie prace źle.

Jedno źródło, dwa widoki

Błędem jest traktowanie ich jako dwóch dokumentów. To dwa widoki tego samego zbioru zmian.

Piszcie changelog na bieżąco, jeden wpis na znaczącą zmianę, każdy oznaczony tym, czym jest: fixed, added, changed, removed, deprecated, security. Trzymajcie wpisy wystarczająco krótkie, by napisanie jednego nie było decyzją. Potem, w momencie wydania, release notes to selekcja i przepisanie: weźcie wpisy, które mają znaczenie dla człowieka, pogrupujcie je według tego, co komuś pozwalają zrobić, i umieśćcie powód na górze.

Ma to praktyczną konsekwencję. Jeśli changelog jest źródłem, musi być danymi strukturalnymi, nie ręcznie utrzymywaną stroną. Wpis potrzebuje typu, daty, wersji i sposobu na wskazanie, dla kogo jest. Gdy to ma, publiczna strona, widget in-app i kanał RSS lub JSON to trzy renderowania jednej rzeczy, i nikt niczego nie przepisuje po drodze do klienta. E-mail z release notes może cytować ten sam wpis, z dowolnego narzędzia, którym wysyłacie e-maile. Automatyzacja changelogu dotyczy tego, który z tych kroków powinna posiadać maszyna. To cały argument za traktowaniem changelogu jako kanału zamiast strony. To także, w pełnej przejrzystości, to, co budujemy, więc czytajcie to jako interes, a nie bezstronny sondaż.

Jeśli masz czas tylko na jedno

Piszcie changelog. Jest tańszy na wpis, użyteczny w dniu, w którym go piszecie, i release notes można z niego później wyprowadzić. Odwrotność nie jest prawdą: nie można zrekonstruować roku zmian z dwunastu e-maili z ogłoszeniami, a ludzie o to poproszą.

Trzymajcie go w stałym formacie, żeby wyprowadzanie pozostało możliwe. Nasza strona przykłady changelogu zbiera wpisy zespołów, które robią to dobrze, a szablon release notes to forma, której używamy, przekształcając zbiór wpisów w coś wartego wysłania.

Uwaga o nazewnictwie

Nic z tego nie jest znormalizowane, i znajdziecie “release notes” używane dla ciągłej listy, a “changelog” dla kwartalnego ogłoszenia. Kłócenie się o słowa nie jest tego warte. Zdecydujcie, którą z dwóch prac wykonuje każdy z waszych artefaktów, nazwijcie go tak, jak już nazywa go wasz zespół, i upewnijcie się, że żaden z nich cicho nie robi obu.

Na jakiej powierzchni wyląduje wynik, to osobna decyzja, omówiona w jak zbudować stronę changeloga.

FAQ

Czy changelog to to samo co release notes? Nie. Changelog to kompletny rejestr, czytany przez tych, którzy czegoś szukają; release notes to wyselekcjonowane ogłoszenie, czytane przez tych, którzy decydują, czy ich to obchodzi. Ta sama zmiana pojawia się w obu, sformułowana inaczej dla każdego czytelnika.

Czy release notes można wygenerować z changelogu? Tak, i to jest właściwy kierunek. Wybierzcie wpisy, które obchodziłyby człowieka, pogrupujcie je według rezultatu, przepiszcie nagłówek. Odwrotność, rekonstruowanie changelogu z ogłoszeń, traci wszystko, co ogłoszenia pominęły.

Gdzie powinien żyć changelog? Gdzieś trwałym i linkowalnym, dokąd czytelnik może dotrzeć bez repozytorium: stronie /changelog, stronie dokumentacji, lub kanale renderowanym w kilku miejscach. Sam CHANGELOG.md dociera do współtwórców, nie do klientów.

Czy changelog powinien zawierać wewnętrzne zmiany? Tak, na dole, po jednej linii każda. Changelog to kompletny rejestr. Release notes też mogą je zawierać, w krótkiej ostatniej sekcji, o ile zmiany, które czytelnik zauważy, są na początku.

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, Szablon notatek wydania