Release notes per le correzioni di bug: voci che servono

Buone release notes per le correzioni di bug descrivono ciò che l’utente ha visto andare storto, non ciò che il codice ha sbagliato. Ogni voce dice chi è stato interessato, da quando, se la correzione è completa e se il lettore deve fare qualcosa, anche solo “nessuna azione necessaria”.

La maggior parte dei team copia una riga dal messaggio di commit. La tabella mostra sei riscritture, e le sezioni dopo spiegano le regole.

Come si scrive una voce di correzione di bug nelle release notes?

Parti dal sintomo con le parole dell’utente, poi chi è stato interessato e da quando, poi lo stato della correzione, poi l’azione. Di solito bastano una o due frasi. La causa nel codice va nella pull request, dove un ingegnere la cercherà.

Il lettore cerca una cosa sola: “riguardava me?” Quattro parti coprono quasi ogni voce:

1. Il sintomo. Cosa è comparso a schermo, nella risposta dell’API o sulla fattura. Cita il testo dell’errore, se c’era, perché le persone lo cercano.
2. L’ambito. Quale piano, piattaforma, versione API o forma dei dati. “Account con più di 50.000 righe” è verificabile. “Alcuni utenti” no.
3. La finestra. Da quale rilascio o data, così un lettore può decidere se il risultato strano di ieri era il bug.
4. L’azione. Rilanciare, risincronizzare, aggiornare, togliere un workaround, oppure niente.

Se gli utenti avevano costruito un workaround, la riga dell’azione è il posto dove dire loro che possono eliminarlo.

Qual è la differenza tra una release note e un changelog?

Un changelog è il registro completo e continuo delle modifiche. Le release notes sono un messaggio scelto e riscritto su un rilascio, per chi sta decidendo se interessarsene. Per le correzioni di bug, il changelog elenca ogni correzione e le note aprono con quelle che un lettore poteva notare.

Un refuso in un tooltip va solo nel changelog. Un’aliquota sbagliata sulle fatture va in entrambi. La divisione completa è in changelog vs release notes, e la forma di un buon insieme di note è in come scrivere release notes.

Keep a Changelog è una comoda convenzione per il lato del registro. Riserva “Fixed” alle correzioni di bug e un titolo “Security” separato alle vulnerabilità, che è la stessa divisione che questo articolo fa per il lettore.

Una correzione di bug è un aggiornamento?

Sì. Una correzione cambia il prodotto, quindi rilasciarla è un aggiornamento. Con il versionamento semantico una correzione retrocompatibile è un rilascio patch, per esempio da 4.2.0 a 4.2.1.

Se il lettore debba fare qualcosa è una questione separata, e la nota dovrebbe rispondere. Una correzione che cambia ciò che osserva un chiamante corretto è vicina a una breaking change, e breaking changes spiega dove passa quel confine.

Quando una correzione merita una voce propria, e quando è una correzione minore?

Dai alla correzione una voce propria quando un utente poteva accorgersi del bug, perderci tempo o dati, o costruirci intorno un workaround. Raggruppala sotto una breve lista “Correzioni minori” quando nessuno fuori dal tuo team poteva vederla. Giudica dall’esperienza del lettore, non dalla dimensione del diff.

Ogni riga del gruppo dovrebbe comunque dire qualcosa: “Corretti alcuni problemi dell’interfaccia” è un segnaposto.

Come si scrive di una regressione?

Nomina il rilascio che l’ha introdotta, chiamala regressione e indica il rilascio che la corregge. Chi ha incontrato il bug sa già che si è rotto, quindi un’ammissione breve e diretta li serve meglio di parole vaghe.

Per esempio: “I risultati di ricerca per query contenenti un trattino tornavano vuoti nella 4.1.0. È corretto nella 4.1.1. Se hai cambiato le tue query per evitare i trattini, puoi rimetterle come prima.”

“Migliorata l’affidabilità della ricerca” suona come una scappatoia a chi ha perso un pomeriggio per colpa del bug. Se la causa è ancora in verifica, dillo, come suggerisce la guida alle release notes di emergenza: la nota non deve mai suonare più sicura di quanto lo sia il team.

Come si annuncia un fix di sicurezza?

Indica la gravità in modo chiaro, nomina le versioni interessate e la versione che le corregge, di’ quanto è urgente l’aggiornamento e includi l’identificatore CVE se esiste. Pubblica i dettagli solo quando gli utenti possono agire su una correzione, seguendo un processo di divulgazione coordinata quando c’è stato un segnalatore.

La sequenza conta: il segnalatore ti avvisa in privato, rilasci la correzione e la nota pubblica esce quando gli utenti possono proteggersi. Il processo di divulgazione coordinata delle vulnerabilità della CISA coordina segnalazione, analisi e divulgazione pubblica delle vulnerabilità. Le regole delle CVE Numbering Authority disciplinano come i record CVE vengono assegnati e pubblicati, e su GitHub un repository security advisory ti permette di redigere l’avviso in privato e richiedere un identificatore.

Una voce di sicurezza di solito porta quattro fatti:

• Cosa poteva fare un attaccante, in una frase e senza una proof of concept.
• Le versioni interessate e la versione che corregge.
• Quanto è urgente: “aggiorna oggi” o “aggiorna al prossimo rilascio”.
• Se hai visto sfruttamento, e il riconoscimento al segnalatore se ha acconsentito.

Lascia fuori i passaggi dell’exploit.

Cosa dovrebbe dire una nota su una correzione di perdita di dati?

Di’ quali dati sono stati interessati, come capire se erano i tuoi e se si possono recuperare. “Nessuna azione necessaria” raramente è vero qui, e la prima domanda del lettore è “i miei dati sono persi?”

Una voce utile dà la condizione che ha fatto perdere i dati (“eliminare una cartella mentre era in corso una sincronizzazione”), la finestra in cui era possibile, un modo per verificare (“apri il Cestino e cerca elementi datati dal 3 al 9 settembre”) e il percorso di recupero. Se i dati non si possono recuperare, dillo. Contatta direttamente anche i clienti interessati, perché la release note non dovrebbe essere l’unico posto in cui qualcuno scopre che i suoi dati sono stati toccati.

Perché “Correzioni di bug e miglioramenti delle prestazioni” è una nota scadente?

Non dà al lettore nulla su cui agire e nasconde le correzioni che qualcuno aspettava. Un cliente che ha segnalato un crash non può sapere se è risolto, e un cliente con un workaround non può sapere se toglierlo.

Ci sono due alternative oneste. Se un rilascio non ha nulla che un lettore possa notare, non pubblicare note e lascia che sia il changelog a tenere il registro. Se ha correzioni, elencale con le parole del lettore:

Prima:
  Correzioni di bug e miglioramenti delle prestazioni.

Dopo:
  Corretto: l'export CSV falliva per i progetti senza tag.
  Corretto: la modalità scura nascondeva il cursore nei commenti.
  Più veloce: la dashboard si apre prima per i workspace
  con più di 100 progetti.

Da dove arrivano le note sulle correzioni di bug?

Arrivano dalla pull request che ha corretto il bug e dalla segnalazione che l’ha innescata. Se le parole di chi ha segnalato viaggiano con la correzione, metà del sintomo è già scritto.

Richiesta di funzionalità o bug spiega perché etichettare correttamente una segnalazione decide chi ne è responsabile. In Changeloop, un bug segnalato tramite il widget diventa un issue di GitHub con l’etichetta bug, e la voce di changelog viene preparata dalla pull request integrata e tenuta in attesa finché una persona la approva prima della pubblicazione. Il template di release notes ti dà la stessa forma di voce per scrivere a mano: sintomo, ambito, finestra, azione.

FAQ

Cosa dovrebbero includere le release notes delle correzioni di bug? Ogni voce dovrebbe nominare il sintomo visto dall’utente, chi è stato interessato, da quale rilascio o data, se la correzione è completa e cosa deve fare il lettore, compreso “niente”.

Ogni correzione di bug va elencata nelle release notes? No. Elenca quelle che un utente poteva notare, che gli hanno fatto perdere tempo o che ha aggirato, e raggruppa le correzioni estetiche o interne sotto una breve lista “Correzioni minori”. Il changelog tiene ogni correzione per chi ha bisogno di consultarla.

Come si scrivono le release notes per un bug che hai introdotto tu? Di’ che era una regressione, nomina il rilascio che l’ha introdotta e quello che la corregge, e di’ ai lettori se possono togliere un workaround. Un’affermazione semplice si legge meglio di parole ammorbidite.

Come si controllano le release notes di un prodotto che usi? Cerca una pagina di changelog o di release notes collegata dal menu di aiuto, dal footer o dalla documentazione del prodotto, oppure nella scheda dei rilasci del repository per i progetti open source.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Modello di release notes