Release notes pe GitHub: generează-le, apoi fă-le lizibile

Release notes pe GitHub sunt descrierea atașată unei lansări pe pagina Releases a repository-ului, iar GitHub poate scrie o primă ciornă pentru voi din pull request-urile integrate de la tag-ul anterior încoace. Ciorna e o listă de titluri de pull request grupate după etichetă, cu o linie de contribuitori și un link de comparare. E exactă, completă și scrisă pentru oamenii care au integrat pull request-urile. Ca s-o transformați în ceva ce un utilizator al proiectului poate citi, aveți nevoie de un fișier .github/release.yml și de o scurtă trecere de editare, ambele descrise mai jos.

Cum generezi automat release notes pe GitHub?

Deschideți formularul de lansare, alegeți sau creați tag-ul și apăsați „Generate release notes”. GitHub găsește tag-ul lansării anterioare, listează fiecare pull request integrat în ramura țintă între cele două și scrie câte o linie per pull request, cu titlul, autorul și numărul lui. Din linia de comandă, gh release create <tag> --generate-notes face același lucru și publică lansarea într-un singur pas; --notes-start-tag schimbă tag-ul anterior de la care pornește intervalul.

Funcția lucrează cu pull request-uri, așa că un repository care integrează direct în main, fără pull request-uri, primește o ciornă goală. Squash merge-urile sunt în regulă, pentru că pull request-ul există în continuare. Commit-urile de merge dintr-o ramură de lungă durată în main produc o singură linie, pentru pull request-ul care face integrarea, fără niciunul dintre pull request-urile integrate mai devreme în acea ramură. Dacă intervalul pare greșit, cauza obișnuită e un tag anterior lipsă sau ordonat greșit; generatorul folosește ultima lansare de pe ramura țintă, iar un tag fără lansare atașată e ignorat.

Pagina GitHub Docs despre release notes generate automat acoperă butonul, iar manualul gh release create acoperă opțiunile CLI.

Ce schimbă release.yml?

.github/release.yml îi spune generatorului ce pull request-uri să lase deoparte și cum să le grupeze pe restul. Fără el, fiecare pull request ajunge într-o singură listă, Dependabot inclus. Cu el, pull request-urile sunt sortate în categorii după etichetă, iar zgomotul etichetat sau scris de boți dispare.

# .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:
        - "*"

Trei reguli merită știute. Categoriile sunt potrivite în ordine, așa că un pull request care are și breaking-change, și bug intră sub primul titlu care se potrivește. Categoria generică "*" e obligatorie dacă vreți ca pull request-urile fără etichetă să apară deloc; fără ea sunt eliminate în tăcere. Iar fișierul afectează doar ce scrie generatorul, așa că o modificare nu atinge notele care există deja. Echipele care etichetează deja pull request-urile pentru un check de changelog în CI pot refolosi aceleași etichete aici.

De ce se citesc prost release notes generate de GitHub?

Pentru că un titlu de pull request e scris pentru reviewer, înainte ca schimbarea să fie terminată, și descrie codul. „Refactor export worker to use streaming” e un titlu bun de pull request și o notă de lansare inutilă, pentru că persoana care citește lansarea vrea să știe că exporturile de peste 100 MB nu mai expiră.

Al doilea motiv e că fiecare pull request integrat primește aceeași greutate. O corecție de o linie la o greșeală de tipar stă lângă un flux nou de autentificare, în ordinea în care s-au integrat. Cititorul trebuie să parcurgă toată lista ca să găsească cele trei linii care îl privesc.

Al treilea e că ciorna nu are introducere. O listă de patruzeci de linii fără nicio propoziție deasupra nu spune nimănui dacă lansarea e sigură de preluat, are nevoie de o migrare sau există doar ca să fixeze o dependență.

Ce ar trebui să schimbe trecerea de editare?

Păstrați lista generată și adăugați la ea, în loc s-o rescrieți de la zero. Lista e pista de audit; numerele pull request-urilor sunt modul în care cineva urmărește o linie înapoi până la diff. Trecerea de editare adaugă părțile pe care generatorul nu are cum să le știe.

1. Scrieți două sau trei propoziții în partea de sus. La ce folosește lansarea, dacă actualizarea cere vreo acțiune și ce trebuie citit mai întâi. Dacă există o schimbare incompatibilă, spuneți-o în prima linie.
2. Rescrieți liniile de care oamenilor le va păsa din perspectiva cititorului: simptomul care a dispărut, lucrul pe care îl pot face acum, setarea care s-a mutat. Lăsați numărul pull request-ului la capătul liniei. Cum se scriu release notes are forma completă; release notes pentru corecții de erori acoperă în mod specific liniile de corecții.
3. Mutați tot ce trebuie să facă un cititor într-o secțiune proprie, cu comanda sau setarea exactă. O schimbare incompatibilă îngropată în lista „Other changes” e un tichet de suport peste o săptămână.
4. Nu ștergeți nimic din lista generată. Restrângeți-o sub un titlu „Lista completă a schimbărilor” dacă e lungă, dar păstrați-o, pentru că o folosesc chiar contribuitorii proiectului.

Făcute așa, release notes pe GitHub iau cam zece minute de editat pentru o lansare obișnuită, iar notele servesc ambele publicuri: rezumatul de sus pentru utilizatori, lista de dedesubt pentru contribuitori.

Ar trebui ca lansarea de pe GitHub să fie changelog-ul vostru?

Doar dacă toți cei care trebuie să afle despre o schimbare citesc deja pagina Releases. Pentru o bibliotecă consumată de dezvoltatori printr-un manager de pachete, asta e adesea adevărat, iar pagina Releases plus un CHANGELOG.md în repository sunt suficiente. Pentru un produs cu utilizatori care nu deschid niciodată GitHub, nu e: pagina de lansare e scrisă la nivelul greșit, stă în spatele unui URL destinat dezvoltatorilor și nu poate fi urmărită de cineva fără cont GitHub.

Tiparul care rezistă e să tratați lansarea de pe GitHub ca înregistrarea pentru dezvoltatori și changelog-ul produsului ca pe cea pentru cititori, cu lansarea trimițând către intrarea din changelog. Tag-uri git, lansări și changelog-ul acoperă cum se aliniază cele trei înregistrări. Dacă changelog-ul produsului e generat din aceleași commit-uri, un generator de changelog vă dă o ciornă și pentru partea aceea, iar împărțirea changelog vs release notes explică unde își are locul fiecare detaliu.

Cum versionezi release notes în sine?

O lansare publicată pe GitHub poate fi editată oricând, iar editarea nu lasă niciun istoric vizibil pe pagină. Pentru majoritatea proiectelor e în regulă. Pentru proiectele în care notele sunt o înregistrare pe care se bazează conformitatea sau clienții, ajută două obiceiuri: păstrați textul canonic în repository (în CHANGELOG.md sau într-un folder docs/releases/) și puneți corpul lansării să trimită la el, și activați lansările imuabile pe repository dacă planul vostru le oferă, ceea ce blochează tag-ul și fișierele atașate odată publicate. GitHub Docs despre gestionarea lansărilor descrie ciornele, pre-lansările și eticheta „latest”, care e atribuită după ordinea versiunilor semantice dacă nu o setați de mână.

FAQ

Pot fi generate automat release notes pe GitHub? Da. Butonul „Generate release notes” din formularul de lansare, opțiunea --generate-notes a comenzii gh release create și endpoint-ul REST generate-notes produc toate o ciornă din pull request-urile integrate de la tag-ul lansării anterioare. Un fișier .github/release.yml controlează gruparea și excluderile.

De ce sunt goale release notes generate de mine? Generatorul listează pull request-uri, așa că commit-urile directe pe ramură nu apar, iar intervalul începe de la ultima lansare de pe ramura țintă, nu de la ultimul tag. Verificați că lansarea anterioară există și că schimbările au intrat prin pull request-uri.

Se aplică release.yml lansărilor care există deja? Nu. Modelează doar notele generate după ce fișierul e la locul lui. Corpurile lansărilor existente rămân cum erau până le editează cineva.

Ar trebui să folosesc release notes pe GitHub sau un CHANGELOG.md? Ambele, dacă proiectul are contribuitori și utilizatori. Pagina de lansare e locul unde se uită dezvoltatorii și unde stau fișierele atașate; fișierul din repository supraviețuiește unei mutări de pe GitHub și poate fi citit offline. Generați release notes, țineți fișierul la zi și legați-le unul de altul.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Generator de changelog, Documentație pentru dezvoltatori