Changelog software: come comunicare nuove feature e aggiornamenti agli utenti

Ci sono modifiche che tecnicamente sono complete, passano i test e arrivano in produzione senza errori. Eppure, dal punto di vista dell’utente, manca ancora un pezzo.

Quel pezzo è la comunicazione.

Se aggiungo una nuova colonna a una tabella, cambio il comportamento di un pulsante, introduco un avviso o finalmente mostro un dato che prima sembrava mancare, il lavoro non dovrebbe considerarsi concluso finché l’utente non ha un modo semplice per capire che qualcosa è cambiato.

Per questo in un progetto ho introdotto una regola molto semplice: ogni modifica visibile nel pannello deve avere la sua voce nel “What’s New”, nello stesso commit della modifica.

Il problema dei changelog scritti a fine sprint

Il modo più comune di gestire le novità di prodotto è anche quello che tende a fallire più facilmente: sviluppare per giorni o settimane e, alla fine, provare a ricordare cosa è cambiato.

A quel punto iniziano le domande:

• questa modifica era visibile agli utenti?
• era una correzione o una nuova funzionalità?
• come funzionava prima?
• qual era il beneficio reale?
• chi se lo ricorda esattamente?

Il problema non è la buona volontà. È che la documentazione viene trattata come un’attività separata dallo sviluppo.

Se la comunicazione di una feature dipende dalla memoria di qualcuno a fine sprint, prima o poi verrà dimenticata.

Spostare il changelog dentro la Definition of Done

La soluzione che preferisco è cambiare completamente il punto di vista: la voce di changelog non è qualcosa da aggiungere dopo una feature.

Fa parte della feature.

La regola può essere espressa così:

Se hai modificato qualcosa che un utente può vedere nel pannello e non hai aggiunto la relativa voce nel What’s New, il task non è finito.

Questo dettaglio cambia parecchio il comportamento del team, perché elimina una categoria separata di lavoro chiamata “aggiornare il changelog”.

Non esiste più un momento successivo in cui ricordarsene. Esiste soltanto il commit che introduce la modifica.

La domanda giusta: l’utente se ne accorgerebbe?

Naturalmente non tutte le modifiche meritano una comunicazione.

Un refactoring interno, una query ottimizzata, un test aggiunto o una modifica infrastrutturale possono essere importanti per il progetto senza avere alcun impatto percepibile dall’utente.

Per decidere se aggiungere una voce utilizzo una domanda molto più utile di “questa modifica è importante?”:

Se non gli diciamo nulla, l’utente si accorgerà da solo che qualcosa è cambiato e capirà perché?

Se la risposta è no, probabilmente serve una voce.

Alcuni esempi:

• una nuova colonna in una tabella;
• un pulsante aggiunto o spostato;
• un nuovo avviso nel pannello;
• un dato che prima non veniva mostrato;
• una procedura che ora si comporta diversamente;
• una modifica che risolve qualcosa che agli utenti sembrava rotto.

Quest’ultimo caso è particolarmente interessante. Una correzione può essere tecnicamente un bug fix, ma se cambia in modo evidente il comportamento percepito dall’utente può avere senso comunicarla.

Mettere la regola direttamente nel task

Una convenzione scritta nella documentazione è utile. Una checkbox nel task è ancora più efficace.

Per ogni attività che può introdurre modifiche al pannello, nella checklist inserisco una voce simile a questa:

- [ ] Voce in config/whats_new.php per la modifica visibile introdotta

È una piccola cosa, ma rende esplicita la Definition of Done nel punto in cui il lavoro viene effettivamente svolto.

Il developer non deve ricordarsi una policy nascosta in una wiki: la vede direttamente insieme alle altre attività.

La stessa regola vale anche per gli agenti AI

Questo approccio diventa ancora più interessante quando nel processo di sviluppo entrano agenti AI.

Un agente può modificare controller, componenti, viste, test e configurazioni molto velocemente. Ma proprio perché può lavorare in autonomia, le convenzioni implicite del team devono diventare esplicite.

Dire genericamente “aggiorna anche il changelog” non basta.

Una regola efficace deve spiegare:

• quando la voce è obbligatoria;
• quando non lo è;
• dove va scritta;
• quando deve essere scritta;
• quale verifica deve essere eseguita dopo la modifica.

In altre parole, bisogna trasformare una buona abitudine del team in una regola verificabile.

Non solo convenzioni: aggiungere una verifica automatica

Dopo aver aggiunto una voce al changelog, faccio eseguire anche una suite di test dedicata:

sail artisan test --compact tests/Feature/WhatsNew

Questo passaggio è importante perché separa due problemi diversi.

La checklist verifica che il developer abbia pensato alla comunicazione. Il test verifica che il meccanismo continui a funzionare correttamente.

Le due cose insieme riducono parecchio la possibilità di arrivare in produzione con una novità non documentata o con un changelog rotto.

Perché deve stare nello stesso commit

Vincolare la voce del What’s New allo stesso commit della modifica non è soltanto una questione di ordine.

Crea una relazione precisa tra codice e comunicazione.

Guardando la cronologia Git diventa immediatamente chiaro quale modifica ha introdotto una determinata voce. Se la feature viene revertita, anche la relativa comunicazione può essere revertita insieme. Durante una code review, reviewer e autore possono verificare contemporaneamente implementazione e messaggio destinato all’utente.

Il changelog smette quindi di essere un documento esterno e diventa parte dell’artefatto software.

Il risultato: meno sorprese per gli utenti

Lo scopo finale non è avere un file perfettamente aggiornato.

Lo scopo è evitare una situazione molto comune nei software gestionali: il team rilascia continuamente miglioramenti, ma gli utenti continuano a lavorare come prima perché nessuno ha detto loro che quelle funzionalità esistono.

Una feature invisibile dal punto di vista della comunicazione rischia di avere molto meno valore di quanto dovrebbe.

Integrare il What’s New nel flusso di sviluppo permette invece di trasformare ogni modifica visibile in un piccolo momento di onboarding continuo.

Una regola semplice che scala bene

La parte che apprezzo di più di questo sistema è che non richiede processi complicati.

Servono soltanto quattro elementi:

1. una regola chiara su cosa deve essere comunicato;
2. una voce nel changelog nello stesso commit;
3. una checkbox nella Definition of Done del task;
4. un test automatico che protegga il meccanismo.

È una convenzione piccola, ma crea un collegamento molto forte tra sviluppo, prodotto e utenti.

E soprattutto elimina quella frase che prima o poi compare in ogni progetto:

“Ah, questa funzionalità esiste già da mesi. Non lo sapevi?”