Keep a Changelog, davvero implementato

Keep a Changelog è una convenzione di una pagina per un CHANGELOG.md: versione più recente prima, una sezione per versione con un numero e una data ISO, voci raggruppate sotto sei tipi (Added, Changed, Deprecated, Removed, Fixed, Security), e una sezione Unreleased in cima per le voci tra i rilasci. La maggior parte dei team che la cita implementa circa due terzi di essa, e il terzo che tralascia è quello che protegge i loro utenti.

Olivier Lacan ha pubblicato Keep a Changelog nel 2014 con una frase invecchiata meglio della maggior parte della prosa sul software: don’t let your friends dump git logs into changelogs. Dieci anni dopo è la cosa più vicina a uno standard che questo angolo del software abbia. Vale la pena leggere la fonte piuttosto che un riassunto; questo riguarda le parti che vengono tralasciate.

Cosa chiede Keep a Changelog?

Un CHANGELOG.md nella radice del repo, più recente prima, con una sezione per versione. Ogni versione porta un numero e una data ISO, e raggruppa le sue voci sotto sei tipi:

Più una sezione Unreleased in cima, così c’è dove mettere una voce nel momento in cui viene mergiata, e così chiunque può vedere cosa arriva.

Questo è quasi tutto. Il resto è il ragionamento: le voci sono per esseri umani, una voce per cambiamento, e il file è un documento piuttosto che un log.

Quali parti di Keep a Changelog vengono tralasciate?

La sezione Unreleased, poi quattro dei sei tipi, Security tra questi, in quest’ordine.

Unreleased scompare per prima. È la sezione senza scadenza, quindi è quella che smette di essere mantenuta, e una volta sparita le voci vengono scritte al momento del rilascio dalla cronologia dei commit. È esattamente il git-log-dump contro cui la specifica avverte all’inizio, raggiunto gradualmente. Automazione del changelog riguarda per lo più tenere viva questa sezione senza che qualcuno debba ricordarselo.

I sei tipi collassano in due. La maggior parte dei changelog reali finisce con Added e Fixed, perché Changed e Deprecated richiedono un giudizio su cosa qualcuno abbia dato per scontato. Quel giudizio è la parte preziosa. Deprecated in particolare è l’unico tipo che è una promessa sul futuro, e tralasciarlo è come una rimozione si trasforma in un incidente; la meccanica per mantenere quella promessa è in come deprecare un’API.

Security smette di essere separato. Una correzione di sicurezza archiviata sotto Fixed è invisibile all’unica lettrice che la stava cercando. Tenetela distinta anche quando la correzione è banale, e specialmente quando preferireste non attirare attenzione su di essa.

Cosa non risponde la specifica?

È un formato di file. Non dice nulla sulle domande che si incontrano subito dopo averla adottata:

• Come lo scopre qualcuno? Un file in un repo raggiunge i collaboratori. Non raggiunge un cliente che non ha mai aperto GitHub.
• E i prodotti senza versioni? Un servizio distribuito continuamente non ha una v4.2.0 per cui raggruppare. La maggior parte dei team sostituisce con date, il che funziona, e la specifica non lo benedice né lo vieta.
• Chi scrive la voce? La specifica assume che lo faccia un umano. Non dice quando.
• E i pubblici multipli? Un file serve gli sviluppatori. Non serve lo stesso contenuto a un’amministratrice non tecnica, e riformattarlo a mano per lei è dove inizia la duplicazione. Changelog vs release notes è la divisione che la specifica vi lascia fare da soli.

Common Changelog, un fork più severo dell’idea, stringe parte di questo: vieta certe formulazioni delle voci, richiede un link al cambiamento, ed è categorico su chi sia il lettore. Vale la pena leggerlo se le parti sciolte di Keep a Changelog sono ciò su cui il vostro team continua a discutere.

Si può automatizzare Keep a Changelog senza scaricare git log?

Sì: derivate la bozza da commit strutturati, mettetela in Unreleased col tipo precompilato, e richiedete che un umano editi la formulazione prima che un rilascio venga tagliato. L’avvertimento della specifica riguarda l’output, non lo strumento. Derivare una bozza da commit va bene. Pubblicare quella bozza non editata è ciò a cui si oppone.

La macchina gestisce raccolta e formattazione, in cui è brava. L’umano gestisce selezione e formulazione, in cui non lo è. Conventional commits copre la divisione su due livelli su cui questo si basa, e quali tipi di commit si mappano su quale delle sei categorie sopra. La nostra rassegna strumenti per il changelog copre cosa esiste per la metà di raccolta.

Dove smette di essere sufficiente Keep a Changelog?

Si ferma alla distribuzione. Keep a Changelog è una buona risposta a “come dovrebbe apparire questo file”. Non è una risposta a “come fanno i nostri utenti a scoprire cosa è cambiato”, perché un file Markdown in un repo è una strategia di distribuzione che funziona solo se i vostri utenti sono collaboratori.

Questo è il secondo ostacolo che colpisce la maggior parte dei team: il file va bene, e nessuno fuori dal team lo legge. Risolverlo significa che le voci devono diventare dati che possono essere resi altrove, il che è un problema diverso dal formattare un file, ed è il motivo per cui esempi di changelog raccoglie pagine pubbliche di changelog piuttosto che file di repository. Come trasformare quelle voci in qualcosa a cui la gente torna è trattato in come costruire una pagina di changelog.

Adottate comunque la specifica. Costa un pomeriggio, rende trattabile il secondo problema, ed è ancora la migliore pagina mai scritta su questo argomento.

FAQ

Keep a Changelog è uno standard? È una convenzione ad ampia adozione, non la specifica di un ente di standardizzazione. Gli strumenti (script di rilascio, linter, parser) assumono la sua forma abbastanza spesso che seguirla compra compatibilità.

Cosa va nella sezione Unreleased? Ogni voce per un cambiamento che è stato mergiato ma non ancora rilasciato in una versione numerata. Quando si taglia un rilascio, la sezione viene rinominata alla versione e data, e una nuova sezione Unreleased vuota va sopra.

Un changelog dovrebbe usare il versionamento semantico? Keep a Changelog lo raccomanda e non lo richiede. Le librerie e le API ne beneficiano; un servizio distribuito continuamente di solito sostituisce con date, cosa che il formato accomoda.

Le correzioni di sicurezza dovrebbero essere nel changelog prima di essere pubbliche? Aggiungete la voce quando la correzione viene rilasciata, con dettaglio sufficiente perché un’operatrice possa agire e non di più. Ritardare la voce fino a una data di divulgazione coordinata è normale; ometterla non lo è.

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, Strumenti di changelog a confronto