Automatyzacja changelogu, i jej granice

Automatyzacja changelogu działa, gdy automatyzuje zbieranie, klasyfikację i publikację, a zatrzymuje się na selekcji i sformułowaniu. Automatyzujcie wszystko, a dostarczycie sformatowany git log; nie automatyzujcie niczego, a changelog jest pisany zrywami, z pamięci, przed wydaniami. Użyteczne pytanie to to, które części automatyzować, nie ile.

Projekty automatyzacji changelogu zawodzą w jednym z dwóch kierunków, i oba są przewidywalne już od pierwszego spotkania projektowego. Automatyzujcie za mało, a changelog staje się dokumentem, który ktoś ma aktualizować, co oznacza, że jest aktualizowany zrywami, przez kogokolwiek, kto wyciągnął najkrótszą słomkę. Automatyzujcie za dużo, a zamienia się w sformatowany git log: kompletny, dokładny, i nieczytany przez nikogo.

Które części changelogu powinny być automatyzowane?

Trzy z czterech kroków. Zbieranie i publikacja całkowicie; klasyfikacja jako pierwszy przebieg z ludzkim nadpisaniem; selekcja i sformułowanie nigdy.

Zbieranie. Wyciąganie zmian z miejsca, gdzie się dzieją (commity, PR, tickety), i wkładanie ich do listy. Automatyzujcie to całkowicie. Ludzie są w tym słabi, to żmudne, i to krok pomijany pod presją terminu. Conventional commits lub etykiety PR to zwykły surowy materiał.

Klasyfikacja. Decydowanie, czy coś jest Added, Fixed, Changed, Deprecated, Removed czy Security. Automatyzujcie pierwszy przebieg z typu commita lub etykiety PR, i pozwólcie osobie nadpisać. Dokładność tutaj wynosi około osiemdziesięciu procent z samych metadanych, a błędne dwadzieścia procent koncentruje się dokładnie na wpisach, które mają znaczenie, ponieważ niejednoznaczność koreluje z ważnością.

Selekcja i sformułowanie. Decydowanie, co powinno być powiedziane czytelnikowi i jak. Nie automatyzujcie tego. To cała wartość artefaktu. Wszystko inne to logistyka.

Publikacja. Przenoszenie ukończonych wpisów na stronę, do kanału, e-maila, widgetu in-app, kanału Slack. Automatyzujcie całkowicie, i z jednego źródła. Tu faktycznie idzie większość ręcznego wysiłku, i prawie nikt tego nie liczy. To także krok, który może powiedzieć osobie, która poprosiła o zmianę, że została wydana, co jest całą treścią zamykania pętli feedbacku od strony changelogu. E-mailowa połowa tego kroku ma własną formę, w szablonie e-maila o aktualizacji produktu.

Ten ostatni punkt warto przemyśleć. Zespoły mają tendencję do postrzegania changelogu jako problemu pisania, a potem spędzają większość czasu na dystrybucji: kopiowaniu wpisów do narzędzia e-mailowego, przeformatowywaniu dla in-app, wklejaniu do Slacka, aktualizowaniu strony dokumentacji. Pisanie zajmuje godzinę. Kopiowanie zajmuje godzinę na każde wydanie, na zawsze, i to część, którą powinna mieć maszyna.

Co się dzieje, gdy granica się przesuwa?

Przesuńcie ją w górę, a dostaniecie zrzut gita. Pełna automatyzacja z commitów produkuje bump deps, fix flaky test, wip i address review comments przed klientami. Każdy zespół, który to zrobił, potem dodał filtr, a filtr to krok selekcji wprowadzony ponownie pod inną nazwą, z gorszą ergonomią.

Przesuńcie ją w dół, a dostaniecie zrywy. Całkowicie ręczne zbieranie oznacza, że wpisy są pisane z pamięci w momencie wydania. To tryb, przed którym Keep a Changelog ostrzega od razu na początku, i cicho się pogarsza: changelog wygląda na utrzymywany aż do dokładnie tego tygodnia, gdy nikt nie miał czasu.

Jak wygląda pipeline automatyzacji changelogu?

Cztery kroki, z dokładnie jedną ludzką bramką, umieszczoną tam, gdzie szkic staje się publiczny.

1. Przy merge’u wyprowadźcie szkicowy wpis z PR: typ z etykiety lub przedrostka commita, tytuł jako pierwszy szkic, link zwrotny do PR, zapisany autor. Umieśćcie go w koszyku niewydanym.
2. Każdy może edytować dowolny szkic w dowolnym momencie, a edycja jest tania. Większość otrzymuje przepisaną jedną linijkę.
3. Wycięcie wydania wymaga, by każdy wpis w koszyku był albo edytowany, albo wyraźnie oznaczony jako wewnętrzny. Ta bramka to cały projekt. Bez niej szkice są wydawane bez edycji w pracowitym tygodniu.
4. Publikacja to fan-out z wydanego zbioru: publiczna strona, kanał, e-mail, widget, post na Slacku. Jedno źródło, kilka renderowań, brak kopiowania.

Krok 3 to jedyne miejsce, gdzie potrzebna jest osoba, i zajmuje około dziesięciu minut na wydanie, gdy szkice są przyzwoite. Tam, gdzie zaangażowana jest prośba klienta, szkic niesie także issue, które zamyka, co pozwala krokowi 4 poinformować proszącego; szablon prośby o funkcję jest zaprojektowany tak, by ten link przetrwał. Miejsce tego kroku w szerszym przepływie wydań to temat procesu zarządzania wydaniami.

Czego automatyzacja wymaga od waszych danych?

Nic z powyższego nie działa, jeśli changelog to plik Markdown, ponieważ pliku nie da się wyrenderować na pięciu powierzchniach bez ponownego parsowania, a parsowanie prozy to sposób, w jaki kończy się na widgecie, który wyświetla pół nagłówka.

Wpisy muszą być strukturalne: typ, data, wersja lub identyfikator wydania, odbiorca, treść i link. Wtedy plik, strona, kanał i e-mail to wszystko widoki. Ten strukturalny punkt to jedyna rzecz warta zrobienia dobrze przed wyborem narzędzia, ponieważ to jest to, czego nie można tanio dodać później. Nic z tego nie działa, jeśli wpis nie zostanie naprawdę utworzony dla każdej zmiany, która go potrzebuje; wymuszanie wpisu w changelogu w CI opisuje, jak sprawić, by pipeline odrzucał merge bez wpisu, zamiast zostawiać ten krok pamięci.

Budujemy changeloop, gdzie changelog jest najpierw kanałem, a dopiero potem stroną, więc czytajcie to jako interes, a nie bezstronną rekomendację; cennik to jedno darmowe repozytorium bez karty, wystarczające, by zobaczyć kształt. Narzędzia do changelogu to nasze zestawienie tego, co jeszcze istnieje, w tym produktów, z którymi konkurujemy, a generator changelogu wykonuje kroki zbierania i klasyfikacji w przeglądarce, jeśli chcecie zobaczyć wyprowadzanie przed zaangażowaniem się w pipeline.

Test

Policzcie minuty między zmergowaną zmianą a widocznością tej zmiany dla klientki, która nie czyta waszego repo. Jeśli większość tych minut to ktoś kopiujący tekst między narzędziami, automatyzacja, której potrzebujecie, jest w publikacji, nie w pisaniu.

FAQ

Czy AI może napisać changelog? Może przygotować szkic. Model, któremu podano zmergowany pull request, najczęściej produkuje użyteczny pierwszy szkic tytułu i treści, co jest lepiej wykonanym zbieraniem i klasyfikacją. Selekcja, czy czytelnik powinien w ogóle zostać poinformowany, i ostateczne sformułowanie, wciąż potrzebują osoby znającej odbiorców, a pipeline, który publikuje szkice bez tej bramki, zautomatyzował niewłaściwy krok.

Jaka jest różnica między generatorem changelogu a automatyzacją changelogu? Generator zamienia commity w sformatowaną listę raz, na żądanie. Automatyzacja działa przy każdym merge’u, utrzymuje koszyk niewydany, warunkuje wydanie ludzką recenzją, i publikuje na każdą powierzchnię z jednego źródła. Generator to pierwszy krok pipeline’u, wykonywany ręcznie.

Czy changelog powinien być automatyzowany z commitów czy z pull requestów? Z pull requestów, gdzie jednostką zmiany jest PR: tytuł i opis są napisane raz, dla całej zmiany, a PR łączy issue, które zamyka. Wyprowadzanie oparte na commitach działa, gdy commit jest jednostką i przestrzega konwencji.

Jak zapobiec publikowaniu wewnętrznych zmian przez automatyzację? Klasyfikujcie chore, ci, test, refactor i aktualizacje zależności jako wewnętrzne domyślnie, i uczyńcie promocję do publicznego świadomym aktem. Odwrócony domyślny stan, publiczne chyba że ktoś to ukryje, to sposób, w jaki bump deps dociera do klientów.

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: Porównanie narzędzi do changeloga, Generator changeloga