Inżynieria

Automatyzacja changelogu: co automatyzować, a czego nie

6 min czytania zaktualizowano

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.

KrokAutomatyzować?Dlaczego
Zbieranie: zmiany z commitów, PR, ticketów na listęCałkowicieŻmudne, pomijane pod presją terminu, maszyny robią to idealnie
Klasyfikacja: Added, Fixed, Changed, Deprecated, Removed, SecurityPierwszy przebieg, ludzkie nadpisanieOkoło 80% trafne z samych metadanych; błędne 20% to wpisy, które mają znaczenie
Selekcja i sformułowanie: co powiedzieć czytelnikowi, i jakNigdyTo cała wartość artefaktu
Publikacja: strona, kanał, e-mail, widget, SlackCałkowicie, z jednego źródłaTam, gdzie faktycznie idzie większość ręcznego wysiłku

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.

Narzędzia open source dobrze pokrywają kroki 1 i 4. git-cliff i conventional-changelog budują szkic z komunikatów commitów; release-please i semantic-release wybierają też wersję i tną wydanie; Changesets sprawia, że każdy pull request niesie własną, ręcznie napisaną notatkę, co pasuje do monorepo; a GitHub potrafi generować release notes ze scalonych pull requestów. Żadne z nich nie dostarcza kroku 3.

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. Jeśli to pisanie zjada minuty, GitHub release notes pokazuje, jak daleko zaprowadzi was wygenerowany szkic.

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

changeloop
Zespół, który tworzy changelog zamykający pętlę. Użytkownicy o coś proszą, Twój zespół to dostarcza, proszący się dowiaduje.