Da qualche mese abbiamo iniziato a tenere traccia delle modifiche pubblicate con i rilasci dei nostri progetti. Non che prima non sapessimo quello che facevamo, ma non avevamo un documento col preciso compito di monitorare il nostro lavoro. In una parola: un changelog.

Il changelog, per noi, ha una duplice importanza. È utile a noi, per sapere esattamente cosa stiamo (e cosa non stiamo) per rilasciare, ma anche per renderci conto di quanto facciamo: ci capita di concentrarci troppo sul lavoro che non riusciamo a svolgere, o che ci sembra di svolgere male, senza invece vedere quanto lavoro di qualità abbiamo fatto. Ed è utile anche al cliente, che vede come prosegue lo sviluppo della sua idea, ed è generalmente contento di vedere sempre una bella lista di nuove funzionalità aggiunte.

Ci siamo accorti che non è facile scrivere un changelog efficace, specialmente se è destinato sia al cliente che agli sviluppatori. Abbiamo sperimentato molto prima di trovare una soluzione che ci piacesse.

Alla fine però l’abbiamo trovata, e ormai non potremmo più fare a meno di tenere i changelog dei nostri progetti. Se anche vuoi saperne di più, questo articolo fa per te!

📙 Cos’è un changelog?

Per capire come tenere un changelog il primo passo da affrontare è capire cosa sia.

Un changelog è, come spiega la parola stessa, un documento in cui vengono riportate tutte le modifiche, risoluzioni di bug ed implementazioni apportate a una versione di un software.

In questo documento viene specificata qualsiasi modifica effettuata a un applicativo, sia essa leggera, pesante, grande o piccola per essenzialmente 2 motivi:

• Tracciare le modifiche tra una versione e l’altra;

• Nel caso in cui si stiano fornendo delle API, o una libreria, è doveroso segnalare agli utilizzatori le modifiche che potrebbero comportare dei problemi in futuro o in determinati contesti (le cosiddette breaking changes).

Dunque, il changelog ha una sua utilità. A questo punto sorge spontanea una domanda: come faccio a tenere un changelog?

Va precisato che non ci sono delle linee guida precise per tenere un changelog, anche se GNU ha provato a definirne alcune. Tuttavia queste linee sono un po’ scarne e orientate ad essere utilizzate su file di testo “vanilla”, il che le rende alquanto inefficienti. È importante tenere a mente che i changelog servono solo ed esclusivamente alle persone e pertanto, per essere chiari e facilmente comprensibili, devono essere un minimo presentabili e fruibili senza dover per forza farsi aumentare la gradazione delle lenti a fine lettura.

Rara immagine di un utente che legge un changelog creato tramite le linee guida GNU

Abbiamo trovato molto interessanti invece le linee guida di keepachangelog.com, un bellissimo progetto che punta a unificare le best practice del mantenimento di un changelog.

Questo sito fornisce un insieme di linee guida più che soddisfacenti in diverse lingue, tra cui l’italiano. Non staremo ad elencarle ma racconteremo piuttosto come ci siamo trovati, quali sono stati i problemi a cui siamo andati incontro e qual è stata l’impostazione che abbiamo dato ai nostri changelog.

Prenderemo come esempio il changelog di un’app fittizia per smartphone, Turntable, un semplice player di musica (ispirato alla reale applicazione Phonograph). 

Detto questo, la prima domanda che ci viene in mente è: in che modo costruire il changelog per renderlo facilmente leggibile?

🧪 Struttura del changelog

La prima idea per strutturare il changelog è stata quella di distinguere i tipi di modifica (bugfix, modifiche e implementazioni, e migliorie), e, per ognuno, l’area di ogni modifica. Le macro aree di Turntable sono “Applicazione Android”, “Applicazione iOS” e “Backend”, quindi, per ogni rilascio, il changelog sarebbe stato così struttutato:

Anche senza contenuti, una suddivisione di questo tipo occupa molto spazio

Può sembrare una suddivisione corretta ed intuitiva, ma in realtà è altamente confusionaria, per due motivi:

• Ci sarebbe della ridondanza, perché una modifica si riflette probabilmente in più macroaree. Avremmo quindi le stesse modifiche riportate più volte;

• Oltre ad essere utile agli sviluppatori, il changelog finisce in mano al cliente, che non ha necessariamente interesse a conoscere l’ubicazione delle modifiche con una precisione capillare.

Abbiamo quindi optato per separare sommariamente i tipi di modifica e, solo nel caso in cui fosse veramente rilevante, segnalare il punto della modifica all’inizio delle descrizione della modifica stessa.

Ecco il risultato:

Un’altra importantissima cosa da tenere a mente è l’ordine dei rilasci nel changelog: il primo deve sempre essere quello più recente, e da lì si prosegue in ordine cronologico fino al rilascio più datato. Questo perché chi legge vuole sapere subito le ultime modifiche presenti, senza dover scrollare fino alla fine del file.

🛒 Contenuto del changelog

Bene, il changelog è ben strutturato, ma cosa ci dobbiamo scrivere dentro? E come?

Che dobbiamo scrivere le modifiche effettuate lo abbiamo capito, sul “come” la domanda si complica: la risposta è “dipende”. Dipende soprattutto da chi deve leggerlo, perché il changelog deve essere pienamente comprensibile al target a cui è rivolto. Faccio un paio di esempi.

Se il changelog è rivolto ad altri sviluppatori sarà bene riportare i cambiamenti con un linguaggio tecnico, magari aggiungendo anche i link ai task nel software di gestione e tracciamento del progetto. Ma in un changelog che verrà letto dall’utilizzatore di un gioco online, raccontare delle corpose modifiche al backend non sarà appropriato: meglio evitare o piuttosto scrivere un semplice “Abbiamo velocizzato il caricamento del gioco”. I giocatori apprezzeranno.

Nel caso di Turntable, il changelog è rivolto agli sviluppatori, per cui la terminologia da utilizzare poteva essere anche abbastanza tecnica, ma non necessariamente seriosa. Abbiamo ritenuto importante linkare i task di Jira, lo strumento usato dagli sviluppatori per tracciare tutte le cose da fare. Abbiamo anche reso le funzionalità più importanti più visibili.

Versione quasi definitiva del changelog

È importante essere allineati con l’utilizzatore finale sulla terminologia, per non rischiare di essere fraintesi. Come abbiamo detto, il changelog di Turntable è rivolto agli sviluppatori, per cui inserire termini tecnici non sarebbe stato un problema.

Oltre ad essere allineati sulla terminologia, è importante la coerenza. In questo modo saremo noi, piano piano, a definire delle terminologie specifiche e, chi starà leggendo il nostro report assocerà man mano i termini da noi usati a qualcosa di concreto.

🎨 Anche l’occhio vuole la sua parte

Quando possibile, ha senso prendere qualche libertà per fare in modo che il changelog sia anche un minimo bello da vedere, oltre che ricco di informazioni.

Non stiamo dicendo a nessuno di fare decorazioni esagerate, ma di avere nuovamente un po’ di buonsenso e di coerenza. Il changelog deve essere prima di tutto consultabile facilmente, per cui niente font particolati o dimensioni del testo minuscole (o gigantesche). Può essere utile usare dei colori, senza esagerare, e tenendo sempre a mente che anche i colori hanno dei significati.

Oltre a questo, è bene mantenere sempre lo stesso stile di scrittura e impaginazione. Per fare un esempio al volo, se avete sempre utilizzato gli elenchi puntati, non iniziate ad un certo punto ad usare quelli numerati senza un valido motivo.

Nel changelog che stiamo portando come esempio abbiamo usato delle emoji per accompagnare i titoli delle sezioni. Non sono invasive, sono rappresentative e sono ben distinte fra loro, così non si confondono.

Non è vietato inserire delle immagini in un changelog, ma è una cosa che solitamente non viene fatta, perché l’obiettivo è fare una panoramica, senza entrare nel dettaglio dei cambiamenti. Per il changelog di Turntable abbiamo pensato a delle pagine di dettaglio separate, linkate nel changelog, e solo lì sono state inserite delle immagini, oltre ad altre informazioni aggiuntive sulla modifica presa in esame. In questo modo il changelog è rimasto pulito, ma abbiamo dato la possibilità di vedere qualche informazione in più sulle modifiche in cui poteva essere utile.

Pagina di dettaglio

Nell’immagine si vede un esempio di pagina di dettaglio, per spiegare meglio le modifiche ad un selettore. In questo caso, il componente grafico era di dimensioni ridotte e quindi era necessario “valorizzarlo” mostrando, appunto, delle anteprime.

La pagina di dettaglio ha, a fianco al titolo, un link che riporta alla pagina principale del changelog (inserito per rendere più semplice la navigazione al fruitore del documento).

Tutti questi accorgimenti possono sembrare piccoli, ma sono proprio le piccole cose che fanno la differenza. Un changelog disordinato diventa inutile: il cliente o l’utente finale non riesce a leggerlo comodamente e lo sviluppatore perde anche la voglia di svilupparlo a lungo andare.

🍳 Considerazioni finali

Abbiamo visto come creare un changelog di tutto rispetto! L’esempio portato era relativo ad un progetto per un cliente, ma non per forza un changelog deve essere serioso: come abbiamo detto, dipende dal lettore finale.

Uno dei changelog che ci è piaciuto di più nell’ultimo periodo è quello di Discord, piattaforma utilizzata solitamente da chi gioca online per comunicare comodamente.

Changelog dell’ultima versione di Discord per Android

Il target di Discord è giovane e dinamico, motivo per cui il changelog è volutamente scritto in maniera scherzosa e leggera, ma riuscendo comunque a comunicare tutte le nuove funzionalità aggiunte.

Un altro changelog fatto molto bene è quello di Telegram. Il changelog è rivolto agli utenti, e in poche parole riesce a racchiudere le (tante) modifiche implementate in ogni versione.

Changelog di Telegram Desktop

A prescindere dal target, però, è sempre importante che i contenuti siano chiari e di facile consultazione, ordinati e non confusionari.

Se l’articolo ti è piaciuto iscriviti alla nostra 📧 newsletter! Posteremo tanti altri contenuti come questo, anche in anteprima!