GitHub release notes: vygenerujte je a udělejte je čitelné

GitHub release notes jsou popis připojený k vydání na stránce Releases repozitáře a GitHub vám jejich první návrh umí napsat sám z pull requestů sloučených od předchozího tagu. Návrh je seznam názvů pull requestů seskupených podle štítků, s řádkem přispěvatelů a odkazem na porovnání. Je přesný, úplný a napsaný pro lidi, kteří ty pull requesty slučovali. Udělat z něj něco, co si přečte uživatel projektu, vyžaduje soubor .github/release.yml a krátkou úpravu, a obojí je popsáno níže.

Jak na GitHubu automaticky vygenerovat release notes?

Otevřete formulář vydání, vyberte nebo vytvořte tag a klikněte na «Generate release notes». GitHub najde tag předchozího vydání, vypíše každý pull request sloučený do cílové větve mezi těmi dvěma a napíše jeden řádek na pull request s jeho názvem, autorem a číslem. Z příkazové řádky dělá totéž gh release create <tag> --generate-notes a vydání v jednom kroku rovnou zveřejní; --notes-start-tag přepíše, od kterého staršího tagu rozsah začíná.

Funkce pracuje s pull requesty, takže repozitář, který merguje přímo do main bez pull requestů, dostane prázdný návrh. Squash merge je v pořádku, protože pull request stále existuje. Merge commity z dlouho žijící větve do main dají jeden řádek za slučující pull request, bez pull requestů, které byly do té větve sloučeny dřív. Pokud rozsah vypadá špatně, obvyklou příčinou je chybějící nebo špatně seřazený předchozí tag; generátor používá poslední vydání na cílové větvi a tag bez připojeného vydání ignoruje.

Stránka GitHub Docs o automaticky generovaných release notes popisuje tlačítko a manuál gh release create popisuje přepínače CLI.

Co mění release.yml?

.github/release.yml říká generátoru, které pull requesty vynechat a jak seskupit zbytek. Bez něj skončí každý pull request v jednom seznamu, včetně Dependabotu. S ním se pull requesty třídí do kategorií podle štítků a šum označený štítkem nebo vytvořený botem zmizí.

# .github/release.yml
changelog:
  exclude:
    labels:
      - skip-changelog
    authors:
      - dependabot
      - renovate
  categories:
    - title: Zásadní změny
      labels:
        - breaking-change
    - title: Nové
      labels:
        - enhancement
    - title: Opraveno
      labels:
        - bug
    - title: Ostatní změny
      labels:
        - "*"

Tři pravidla, která stojí za to znát. Kategorie se porovnávají v pořadí, takže pull request se štítky breaking-change i bug spadne pod první nadpis, který odpovídá. Zástupný "*" je nutný, pokud se mají pull requesty bez štítku vůbec objevit; bez něj se potichu vynechají. A soubor ovlivňuje jen to, co generátor napíše, takže jeho změna se nedotkne poznámek, které už existují. Týmy, které pull requesty štítkují kvůli kontrole changelogu v CI, tu mohou použít stejné štítky.

Proč se vygenerované GitHub release notes špatně čtou?

Protože název pull requestu je napsaný pro reviewera, ještě než je změna hotová, a popisuje kód. «Refaktor export workeru na streamování» je dobrý název pull requestu a nepoužitelná release note, protože člověk, který čte vydání, chce vědět, že exporty nad 100 MB už nevyprší.

Druhý důvod je, že každý sloučený pull request má stejnou váhu. Jednořádková oprava překlepu sedí vedle nového přihlašovacího flow, v pořadí, v jakém se sloučily. Čtenář musí projet celý seznam, aby našel tři řádky, které se ho týkají.

Třetí je, že návrh nemá úvod. Seznam čtyřiceti řádků bez věty nad ním nikomu neřekne, zda je vydání bezpečné nasadit, zda potřebuje migraci, nebo zda existuje jen kvůli připnutí závislosti.

Co má úprava změnit?

Vygenerovaný seznam nechte a přidávejte k němu, místo abyste psali od nuly. Seznam je auditní stopa; čísla pull requestů jsou to, přes co si někdo dohledá řádek až k diffu. Úprava přidává části, které generátor nemůže znát.

1. Napište nahoru dvě nebo tři věty. K čemu vydání je, zda aktualizace vyžaduje nějakou akci a co číst jako první. Pokud je tam zásadní změna, řekněte to v první větě.
2. Přepište řádky, na kterých lidem záleží, ze strany čtenáře: příznak, který zmizel, věc, kterou teď mohou udělat, nastavení, které se přesunulo. Číslo pull requestu nechte na konci řádku. Jak psát release notes má celý tvar; release notes k opravám chyb se věnují konkrétně řádkům s opravami.
3. Cokoli, co musí čtenář udělat, přesuňte do vlastní sekce, s přesným příkazem nebo nastavením. Zásadní změna zahrabaná v seznamu «Ostatní změny» je za týden tiket na podpoře.
4. Z vygenerovaného seznamu nic nemažte. Pokud je dlouhý, sbalte ho pod nadpis «Úplný seznam změn», ale nechte ho tam, protože ho používají přispěvatelé projektu.

Takto zabere úprava GitHub release notes u typického vydání asi deset minut a poznámky slouží oběma publikům: souhrn nahoře uživatelům, seznam pod ním přispěvatelům.

Má být GitHub release vaším changelogem?

Jen pokud každý, kdo se o změně potřebuje dozvědět, už stránku Releases čte. U knihovny, kterou vývojáři berou přes správce balíčků, to často platí a stránka Releases plus CHANGELOG.md v repozitáři stačí. U produktu s uživateli, kteří GitHub nikdy neotevřou, ne: stránka vydání je psaná na špatné úrovni, žije za URL určenou vývojářům a bez účtu na GitHubu se k ní nedá přihlásit k odběru.

Vzor, který obstojí, je brát GitHub release jako záznam pro vývojáře a produktový changelog jako záznam pro čtenáře, s tím, že vydání odkazuje na záznam v changelogu. Git tagy, release a changelog popisuje, jak se ty tři záznamy skládají. Pokud se produktový changelog generuje ze stejných commitů, generátor changelogu dá návrh i pro tuto stranu a rozdělení changelog vs release notes vysvětluje, který detail kam patří.

Jak verzovat samotné release notes?

Zveřejněné vydání na GitHubu lze kdykoli upravit a úprava nenechá na stránce žádnou viditelnou historii. Pro většinu projektů to nevadí. U projektů, kde jsou poznámky záznamem, na který se spoléhá compliance nebo zákazníci, pomáhají dva návyky: držet kanonický text v repozitáři (CHANGELOG.md nebo složka docs/releases/) a nechat tělo vydání na něj odkazovat, a zapnout na repozitáři neměnná vydání, pokud to váš tarif nabízí, což po zveřejnění zamkne tag i přílohy. GitHub Docs o správě vydání popisují koncepty, předběžná vydání a označení «latest», které se přiděluje podle pořadí sémantických verzí, pokud ho nenastavíte ručně.

FAQ

Dají se GitHub release notes generovat automaticky? Ano. Tlačítko «Generate release notes» ve formuláři vydání, přepínač --generate-notes u gh release create a REST endpoint generate-notes všechny vytvoří návrh z pull requestů sloučených od tagu předchozího vydání. Soubor .github/release.yml řídí seskupení a vynechání.

Proč jsou moje vygenerované release notes prázdné? Generátor vypisuje pull requesty, takže přímé commity do větve se neobjeví, a rozsah začíná u posledního vydání na cílové větvi, ne u posledního tagu. Zkontrolujte, že předchozí vydání existuje a že změny přišly přes pull requesty.

Platí release.yml i pro vydání, která už existují? Ne. Tvaruje jen poznámky vygenerované poté, co je soubor na místě. Těla existujících vydání zůstávají, jak byla, dokud je někdo neupraví.

Mám používat GitHub release notes, nebo CHANGELOG.md? Obojí, pokud má projekt přispěvatele i uživatele. Stránka vydání je tam, kam se dívají vývojáři a kde žijí přílohy; soubor v repozitáři přežije odchod z GitHubu a dá se číst offline. Release notes vygenerujte, soubor udržujte aktuální a propojte jedno s druhým.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Generátor changelogu, Dokumentace pro vývojáře