GitHub release notes: wygenerujcie je, potem zredagujcie

GitHub release notes to opis dołączony do wydania na stronie Releases repozytorium, a GitHub potrafi napisać ich pierwszy szkic za was z pull requestów scalonych od poprzedniego tagu. Szkic to lista tytułów pull requestów pogrupowana według etykiet, z linią współtwórców i linkiem do porównania. Jest dokładny, kompletny i napisany dla ludzi, którzy te pull requesty scalali. Zamiana go w coś, co przeczyta użytkownik projektu, wymaga pliku .github/release.yml i krótkiej redakcji, i oba opisujemy poniżej.

Jak automatycznie wygenerować release notes na GitHubie?

Otwórzcie formularz wydania, wybierzcie lub utwórzcie tag i kliknijcie “Generate release notes”. GitHub znajduje tag poprzedniego wydania, wylicza każdy pull request scalony do gałęzi docelowej między nimi i pisze po jednej linii na pull request z jego tytułem, autorem i numerem. Z linii poleceń gh release create <tag> --generate-notes robi to samo i publikuje wydanie w jednym kroku; --notes-start-tag nadpisuje, od którego wcześniejszego tagu zaczyna się zakres.

Funkcja pracuje na pull requestach, więc repozytorium, które scala prosto do main bez pull requestów, dostaje pusty szkic. Squash merge jest w porządku, bo pull request nadal istnieje. Commity scalające długo żyjącą gałąź do main dają jedną linię za scalający pull request, bez żadnego z pull requestów, które wcześniej scalono do tamtej gałęzi. Jeśli zakres wygląda źle, zwykłą przyczyną jest brakujący lub źle uporządkowany poprzedni tag; generator używa najnowszego wydania na gałęzi docelowej, a tag bez dołączonego wydania jest ignorowany.

Strona GitHub Docs o automatycznie generowanych release notes opisuje przycisk, a instrukcja gh release create opisuje flagi CLI.

Co zmienia release.yml?

.github/release.yml mówi generatorowi, które pull requesty pominąć i jak pogrupować resztę. Bez niego każdy pull request ląduje na jednej liście, razem z Dependabotem. Z nim pull requesty są sortowane do kategorii według etykiet, a oznaczony etykietą lub pisany przez boty szum znika.

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
    authors:
      - dependabot
      - renovate
  categories:
    - title: Breaking changes
      labels:
        - breaking-change
    - title: New
      labels:
        - enhancement
    - title: Fixed
      labels:
        - bug
    - title: Other changes
      labels:
        - "*"

Trzy zasady warte znajomości. Kategorie są dopasowywane po kolei, więc pull request z etykietami breaking-change i bug trafia pod pierwszy pasujący nagłówek. Zbiorcze "*" jest wymagane, jeśli nieoznaczone pull requesty mają się w ogóle pojawić; bez niego są po cichu pomijane. A plik wpływa tylko na to, co generator pisze, więc jego zmiana nie dotyka już istniejących notatek. Zespoły, które już etykietują pull requesty na potrzeby sprawdzania changelogu w CI, mogą użyć tych samych etykiet tutaj.

Dlaczego wygenerowane GitHub release notes źle się czyta?

Bo tytuł pull requesta jest pisany dla recenzenta, zanim zmiana jest skończona, i opisuje kod. “Refactor export worker to use streaming” to dobry tytuł pull requesta i bezużyteczna release note, bo osoba czytająca wydanie chce wiedzieć, że eksporty powyżej 100 MB już nie przekraczają limitu czasu.

Drugi powód jest taki, że każdy scalony pull request ma tę samą wagę. Jednoliniowa poprawka literówki siedzi obok nowego przepływu uwierzytelniania, w kolejności, w jakiej je scalono. Czytelnik musi przejrzeć całą listę, żeby znaleźć trzy linie, które go dotyczą.

Trzeci jest taki, że szkic nie ma otwarcia. Lista czterdziestu linii bez zdania nad nią nie mówi nikomu, czy to wydanie można bezpiecznie wziąć, czy wymaga migracji, czy istnieje tylko po to, żeby przypiąć zależność.

Co powinna zmienić redakcja?

Zachowajcie wygenerowaną listę i dopiszcie do niej, zamiast pisać od zera. Lista to ślad audytowy; numery pull requestów to sposób, w jaki ktoś dociera od linii do diffa. Redakcja dodaje to, czego generator nie może wiedzieć.

1. Napiszcie dwa lub trzy zdania na górze. Po co jest to wydanie, czy aktualizacja wymaga jakiegoś działania i co przeczytać najpierw. Jeśli jest zmiana łamiąca kompatybilność, powiedzcie to w pierwszej linii.
2. Przepiszcie linie, na których ludziom zależy, od strony czytelnika: objaw, który zniknął, rzecz, którą teraz mogą zrobić, ustawienie, które się przeniosło. Zostawcie numer pull requesta na końcu linii. Jak pisać release notes daje pełny kształt; release notes poprawek błędów omawia konkretnie linie o poprawkach.
3. Przenieście wszystko, co czytelnik musi zrobić, do osobnej sekcji, z dokładnym poleceniem lub ustawieniem. Zmiana łamiąca kompatybilność zakopana na liście “Other changes” to zgłoszenie do supportu za tydzień.
4. Nie usuwajcie niczego z wygenerowanej listy. Zwińcie ją pod nagłówkiem “Pełna lista zmian”, jeśli jest długa, ale zachowajcie ją, bo korzystają z niej współtwórcy projektu.

Zrobione w ten sposób GitHub release notes zajmują około dziesięciu minut redakcji dla typowego wydania, a notatki służą obu odbiorcom: podsumowanie na górze użytkownikom, lista poniżej współtwórcom.

Czy wydanie na GitHubie powinno być waszym changelogiem?

Tylko jeśli wszyscy, którzy muszą wiedzieć o zmianie, już czytają stronę Releases. Dla biblioteki używanej przez deweloperów przez menedżer pakietów często tak jest, i strona Releases plus CHANGELOG.md w repozytorium wystarczą. Dla produktu z użytkownikami, którzy nigdy nie otwierają GitHuba, nie: strona wydania jest pisana na złym poziomie, żyje pod adresem dla deweloperów i nie może jej subskrybować ktoś bez konta GitHub.

Wzorzec, który się sprawdza, to traktowanie wydania na GitHubie jako zapisu dla deweloperów, a changelogu produktu jako zapisu dla czytelników, z wydaniem linkującym do wpisu changelogu. Tagi gita, wydania i changelog opisuje, jak te trzy zapisy się układają. Jeśli changelog produktu jest generowany z tych samych commitów, generator changelogu daje szkic także dla tej strony, a podział changelog vs release notes wyjaśnia, który szczegół gdzie należy.

Jak wersjonować same release notes?

Opublikowane wydanie na GitHubie można edytować w dowolnym momencie, a edycja nie zostawia widocznej historii na stronie. Dla większości projektów to w porządku. Dla projektów, w których notatki są zapisem, na którym polega compliance lub klienci, pomagają dwa nawyki: trzymajcie kanoniczny tekst w repozytorium (CHANGELOG.md albo folder docs/releases/) i niech treść wydania do niego odsyła, oraz włączcie niezmienne wydania w repozytorium, jeśli wasz plan to oferuje, co blokuje tag i zasoby po publikacji. GitHub Docs o zarządzaniu wydaniami opisują szkice, wydania wstępne i etykietę “latest”, przyznawaną według kolejności wersji semantycznej, chyba że ustawicie ją ręcznie.

FAQ

Czy GitHub release notes można generować automatycznie? Tak. Przycisk “Generate release notes” w formularzu wydania, flaga --generate-notes w gh release create i endpoint REST generate-notes tworzą szkic z pull requestów scalonych od tagu poprzedniego wydania. Plik .github/release.yml steruje grupowaniem i wykluczeniami.

Dlaczego moje wygenerowane release notes są puste? Generator wylicza pull requesty, więc bezpośrednie commity do gałęzi się nie pojawiają, a zakres zaczyna się od najnowszego wydania na gałęzi docelowej, a nie od najnowszego tagu. Sprawdźcie, czy poprzednie wydanie istnieje i czy zmiany weszły przez pull requesty.

Czy release.yml dotyczy wydań, które już istnieją? Nie. Kształtuje tylko notatki wygenerowane po tym, jak plik jest na miejscu. Istniejące treści wydań zostają takie, jakie były, dopóki ktoś ich nie zedytuje.

Używać GitHub release notes czy CHANGELOG.md? Obu, jeśli projekt ma współtwórców i użytkowników. Strona wydania to miejsce, gdzie patrzą deweloperzy i gdzie leżą zasoby; plik w repozytorium przetrwa przeprowadzkę z GitHuba i da się go czytać offline. Generujcie release notes, trzymajcie plik aktualny i linkujcie jedno do drugiego.

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: Generator changeloga, Dokumentacja dla deweloperów