Changelog vs release notes: qual è la differenza?

Un changelog è un registro continuo e cumulativo di tutto ciò che è cambiato, scritto per qualcuno che sta cercando qualcosa. Le release notes sono un messaggio curato su un rilascio, scritto per qualcuno che decide se lo riguarda. La differenza è di pubblico, non di formattazione, e la maggior parte dei team ne ha bisogno di entrambi: uno come riferimento, uno come annuncio, derivati dalle stesse voci.

La maggior parte dei team finisce con uno di questi per caso e l’altro su richiesta. Iniziate con un changelog perché uno sviluppatore vuole un registro di cosa è stato rilasciato. Mesi dopo qualcuno del supporto chiede perché i clienti non sapessero di una funzione live da aprile, e ora vi servono release notes.

Changelog vs release notes, a confronto

Cos’è un changelog?

Un changelog è un registro cronologico, quasi completo, di ciò che è cambiato, più recente prima, con ogni voce tipizzata (added, changed, deprecated, removed, fixed, security) e datata. Il suo lettore ha già deciso che gli importa. Sta cercando qualcosa: quando è cambiato un comportamento, se un bug è corretto, quale versione ha introdotto un flag. La completezza è tutto il valore, per cui la convenzione Keep a Changelog dedica la maggior parte della sua unica pagina alla struttura e quasi niente alla prosa.

Cosa sono le release notes?

Le release notes sono un messaggio selettivo, scritto in prosa, su un rilascio. Il loro lettore non ha ancora deciso nulla. Sta decidendo se questo rilascio gli importa, e se deve fare qualcosa al riguardo. La selezione è tutto il valore: una release note che elenca tutto è un changelog con paragrafi, e fallisce il lettore allo stesso modo in cui un changelog che salta cose fallisce il suo. Come scrivere release notes riguarda la selezione e la formulazione.

Servono sia un changelog che le release notes?

Ne servono entrambi una volta che i vostri due pubblici vogliono cose diverse; fino ad allora un solo artefatto che fa entrambi i lavori è corretto. I team piccoli pubblicano una singola pagina /changelog con un breve paragrafo in cima a ogni voce, e per un po’ quello serve altrettanto bene uno sviluppatore che cerca una correzione e un cliente che scorre in cerca di novità. Dividere troppo presto vi dà due cose da mantenere e una delle due marcirà.

La divisione vale la pena quando iniziano a succedere queste cose:

• Le vostre voci di changelog sono cresciute con paragrafi esplicativi che gli sviluppatori scorrono senza leggere.
• O il contrario: i vostri annunci di rilascio hanno iniziato a elencare aggiornamenti di dipendenze.
• Il supporto sta copiando voci nelle email e riscrivendole per strada.
• Qualcuno chiede “solo i cambiamenti che rompono qualcosa” e non potete filtrarli.

Quell’ultimo è il vero segnale. Se nessuno può rispondere “cosa è cambiato che mi riguarda” senza leggere tutto, avete un artefatto che fa male due lavori.

Una fonte, due viste

L’errore è trattarli come due documenti. Sono due viste sullo stesso insieme di cambiamenti.

Scrivete il changelog man mano, una voce per ogni cambiamento significativo, ciascuna etichettata con cosa è: fixed, added, changed, removed, deprecated, security. Mantenete le voci abbastanza brevi che scriverne una non sia una decisione. Poi, al momento del rilascio, le release notes sono una selezione e una riscrittura: prendete le voci che importano a una persona, raggruppatele per cosa permettono di fare, e mettete il motivo in cima.

Questo ha una conseguenza pratica. Se il changelog è la fonte, deve essere dati strutturati, non una pagina mantenuta a mano. Una voce ha bisogno di un tipo, una data, una versione, e un modo di dire per chi è. Una volta che ha quello, la pagina pubblica, il widget in-app e il feed RSS o JSON sono tre rendering di una cosa sola, e nessuno riscrive nulla lungo il percorso verso un cliente. Un’email di release notes può citare la stessa voce, da qualunque strumento invii le vostre email. Automazione del changelog riguarda quale di questi passi dovrebbe possedere una macchina. Questo è tutto l’argomento per trattare un changelog come un feed piuttosto che una pagina. È anche, con trasparenza, ciò che costruiamo, quindi leggetelo come un interesse piuttosto che un sondaggio neutrale.

Se avete tempo solo per uno

Scrivete il changelog. Costa meno per voce, è utile il giorno in cui lo scrivete, e le release notes possono essere derivate da esso dopo. Il contrario non è vero: non potete ricostruire un anno di cambiamenti da dodici email di annuncio, e la gente ve lo chiederà.

Mantenetelo in un formato fisso così che la derivazione resti possibile. La nostra pagina di esempi di changelog raccoglie voci di team che lo fanno bene, e la release notes template è la forma che usiamo quando trasformiamo un insieme di voci in qualcosa che vale la pena inviare.

Una nota sui nomi

Niente di tutto questo è standardizzato, e troverete “release notes” usato per una lista continua e “changelog” usato per un annuncio trimestrale. Non vale la pena discutere sulle parole. Decidete quale dei due lavori sta facendo ciascuno dei vostri artefatti, chiamatelo come il vostro team già lo chiama, e assicuratevi che nessuno dei due stia facendo entrambi in silenzio.

Su quale superficie finisca il risultato è una decisione a parte, trattata in come costruire una pagina di changelog.

FAQ

Un changelog è lo stesso delle release notes? No. Un changelog è il registro completo, letto da chi cerca qualcosa; le release notes sono l’annuncio selezionato, letto da chi decide se interessarsene. Lo stesso cambiamento appare in entrambi, formulato diversamente per ciascun lettore.

Le release notes possono essere generate da un changelog? Sì, ed è la direzione giusta. Selezionate le voci che importerebbero a una persona, raggruppatele per risultato, riscrivete il titolo. Il contrario, ricostruire un changelog dagli annunci, perde tutto ciò che gli annunci hanno lasciato fuori.

Dove dovrebbe vivere un changelog? Da qualche parte permanente e collegabile a cui il lettore può arrivare senza un repository: una pagina /changelog, un sito docs, o un feed che si rende in più posti. Un CHANGELOG.md da solo raggiunge i collaboratori, non i clienti.

Un changelog dovrebbe includere cambiamenti interni? Sì, in fondo, una riga ciascuno. Il changelog è il registro completo. Anche le release notes possono tenerli, in una breve sezione finale, purché vengano prima i cambiamenti che un lettore noterà.

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: Esempi di changelog, Modello di release notes