changeloop blog

Release notes per le correzioni di bug: voci che servono

Fri, 02 Oct 2026 00:00:00 GMT

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.

Prima (il messaggio di commit)	Dopo (il sintomo)
Fixed null pointer in export handler	Gli export non falliscono più con "Qualcosa è andato storto" quando un progetto non ha tag. Rilancia gli export falliti dal 3 settembre.
Resolved race condition in sync worker	Le modifiche fatte su due dispositivi a pochi secondi di distanza non si sovrascrivono più. Non devi fare nulla.
Fix timezone bug	I report programmati ora partono all'ora impostata. Gli account a est di UTC vedevano i report fino a un giorno prima dal 12 agosto. Nessuna modifica necessaria.
Patched XSS in comment renderer	Fix di sicurezza: un commento costruito ad arte poteva eseguire uno script nel browser di un altro utente. Aggiorna alla 4.2.1 oggi. Nei nostri log non abbiamo visto sfruttamento.
Fixed regression from 4.1.0	La ricerca funziona di nuovo per le query che contengono un trattino. Si era rotta nella 4.1.0 ed è corretta nella 4.1.1.
Bug fixes and performance improvements	Di' quali. Vedi l'ultima sezione.

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:

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.
L'ambito. Quale piano, piattaforma, versione API o forma dei dati. "Account con più di 50.000 righe" è verificabile. "Alcuni utenti" no.
La finestra. Da quale rilascio o data, così un lettore può decidere se il risultato strano di ieri era il bug.
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.

Ha una voce propria	Va nella lista delle correzioni minori
Segnalato da un cliente o subìto da molti	Difetto estetico in una schermata aperta di rado
Ha causato output sbagliato, job falliti o lavoro perso	Refuso, spaziatura, un'icona disallineata
Richiede un'azione dal lettore	Correzione in uno strumento interno o in una pagina admin
Una regressione di un rilascio recente	Errore visto solo in un ambiente di test
Tocca fatturazione, permessi o dati	Testo dei log, aggiornamenti di dipendenze senza effetto per l'utente

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.

Come chiedere feedback ai clienti in un prodotto software

Fri, 02 Oct 2026 00:00:00 GMT

Per chiedere feedback ai clienti in un prodotto software, fai una domanda specifica su qualcosa che l'utente ha appena fatto, nel punto in cui l'ha fatto. "Com'è andata l'esportazione di quel report?" subito dopo un export ottiene una risposta. "Dicci cosa pensi del nostro prodotto" in un footer ottiene silenzio. Il resto di questa pagina sono i momenti, i canali e le formulazioni esatte.

La maggior parte dei consigli su questo tema è scritta per negozi e sportelli di assistenza. Un team software sa esattamente cosa ha fatto l'utente un secondo fa, quindi la domanda può riguardare quello.

Momento	Dove chiedere	Domanda pronta all'uso
Subito dopo che un'attività finisce	Nell'app, accanto al risultato	"Quell'export ha fatto quello che ti serviva?"
Dopo il primo uso di una nuova funzionalità	Nell'app, una sola volta	"Cosa stavi cercando di fare con Bulk Edit?"
Dopo la risoluzione di un ticket di supporto	Nel thread di supporto	"Ha risolto, o c'è ancora qualcosa che non va?"
Dopo che un utente si ferma o abbandona un flusso	Email, un giorno dopo	"Ti sei fermato al passo 3 della configurazione. Cosa ti ha bloccato?"
Dopo 30 giorni di uso regolare	Email da una persona con nome e cognome	"Qual è l'unica cosa che cambieresti?"
Quando un utente disdice	Nel flusso di disdetta	"Cosa ti ha fatto decidere di andare via oggi?"
Dopo aver rilasciato qualcosa che avevano chiesto	Dove l'avevano chiesto	"Avevi chiesto l'import CSV. È online. Copre il tuo caso?"

Qual è il momento giusto per chiedere feedback?

Il momento giusto è subito dopo che l'utente ha finito qualcosa, mentre i dettagli sono ancora freschi. Una domanda che segue un'azione ottiene una risposta su quell'azione. Una domanda che arriva dal nulla ottiene una risposta sull'umore della persona in quel momento, oppure nessuna.

Non chiedere alla registrazione, perché nessuno ha ancora usato niente. Non chiedere nel mezzo di un'attività, perché interrompi proprio ciò che vuoi capire. Quando una persona ha risposto, lasciala in pace finché non hai qualcosa da comunicarle.

Dove si dovrebbe chiedere feedback ai clienti?

Chiedi nel posto in cui è avvenuta l'esperienza. Una richiesta nell'app va bene per una domanda su una schermata. Il thread di supporto va bene per una domanda su una correzione. L'email va bene per una domanda su una settimana di uso, o su un flusso che la persona ha abbandonato. Una chiamata va bene per le domande che non puoi prevedere.

Ogni canale dà un tipo diverso di risposta:

Nell'app: risposte brevi, immediate e specifiche, ma solo da chi è presente. Da chi se n'è andato non senti nulla.
Thread di supporto: da persone già abbastanza frustrate da scrivere. Ottimo per trovare cose rotte, scarso per giudicare il resto del prodotto.
Email: risposte più lunghe da meno persone, e l'unico modo per raggiungere gli utenti che si sono fatti silenziosi. Scrivila come una breve nota da una persona con un nome, con una sola domanda dentro.
Intervista: il modo per capire perché le persone fanno ciò che fanno. Chiedi loro di mostrarti come lavorano, e stai zitto mentre lo fanno.

Qualità del segnale nel feedback spiega come valutare ciò che ogni canale ti dice.

Come si chiede un feedback in modo professionale?

Sii specifico sull'oggetto, spiega perché lo chiedi e fai in modo che rispondere costi meno di un minuto. Una richiesta professionale nomina il momento, chiarisce che una persona leggerà la risposta e non si scusa per l'interruzione.

Nomina l'azione esatta ("l'export che hai appena lanciato"), chiedi una cosa sola, usa una casella di testo libero senza campi obbligatori e firma con un nome di battesimo.

Qual è una buona frase per chiedere un feedback?

Una buona frase è una domanda su un momento specifico a cui si può rispondere in poche parole. Confronta le due colonne qui sotto. Quelle a sinistra si possono liquidare con una scrollata di spalle. Quelle a destra obbligano la persona a ricordare qualcosa di reale.

Richiesta debole	Richiesta più forte
"Feedback?"	"Qual è stata la parte più difficile della configurazione?"
"Ti piace il nostro prodotto?"	"Per cosa l'hai usato la settimana scorsa?"
"Valuta la tua esperienza da 1 a 10."	"Oggi sei riuscito a fare quello per cui eri venuto?"
"Dicci come possiamo migliorare."	"Qual è una cosa che ti ha rallentato questa settimana?"
"Ci consiglieresti?"	"A chi l'hai mostrato l'ultima volta, e cosa hai detto?"

Un'altra che funziona quasi ovunque: "Cosa usi al posto nostro quando questo non fa per te?" Fa emergere il vero concorrente, che spesso è un foglio di calcolo.

Quali sono i modi peggiori di chiedere feedback?

Le richieste peggiori sono generiche, premature, lunghe o tendenziose. Hanno un problema in comune: la persona non può rispondere senza fare il lavoro di riflessione che avresti dovuto fare tu.

"Compila il nostro sondaggio di 20 domande." Chi arriva in fondo è chi ha più tempo libero o le opinioni più forti.
Un popup nella prima pagina dopo il login. L'utente era venuto per fare qualcosa e glielo hai impedito. Chiuderlo è l'unica risposta sensata.
"Ci farebbe piacere il tuo feedback!" senza nessuna domanda. Chiede all'utente di inventarsi l'argomento.
Una domanda tendenziosa: "Quanto ami la nuova dashboard?" Ottieni un sì e non impari niente.
Una valutazione senza seguito. Un 6 su 10 ti dice l'umore. Non ti dice cosa cambiare.
Chiedere e poi tacere. Ti costa il giro successivo, come spieghiamo più avanti.

Come si chiama il feedback dei clienti su un prodotto?

Il feedback su un prodotto si chiama di solito feedback di prodotto, e si divide in due tipi. Una segnalazione di bug dice che qualcosa non funziona come previsto. Una richiesta di funzionalità dice che manca qualcosa. La distinzione decide chi se ne occupa per primo, e richiesta di funzionalità o bug traccia quel confine. Un terzo tipo, gli elogi, vale la pena di conservarlo e citarlo con il permesso.

Un modulo di feedback che offre "Bug" e "Richiesta di funzionalità" come prima scelta fa questa prima smistata al posto tuo.

Cosa si fa con le risposte?

Metti ogni risposta dove il team già lavora, con le parole della persona intatte. Una riga di testo citato vale più del tuo riassunto. Etichettala per tipo e urgenza approssimativa, unisci i duplicati e decidi: costruirla, metterla da parte o rifiutarla.

Anche rifiutare è una risposta. "Non la costruiremo, ed ecco perché" mette fine all'attesa, e rifiutare le richieste di funzionalità ha delle formulazioni per farlo. Per l'infrastruttura, tracciare le richieste di funzionalità descrive come portare le richieste da cinque canali in un'unica lista. Se raccogli le richieste per iscritto, un template di richiesta di funzionalità le rende confrontabili.

Il widget di Changeloop registra ogni invio come un issue di GitHub, così il feedback finisce accanto al codice che lo risolverà. Con qualsiasi strumento la regola è la stessa: una lista, un responsabile, nessuna risposta dimenticata nella casella di qualcuno.

Perché dire alle persone cosa è stato rilasciato?

Mostra alla persona che rispondere è valsa il suo tempo. Un utente che ti ha detto qualcosa e poi sente "è stato rilasciato, grazie" ha un motivo per rispondere ancora. Chi non sente niente conclude che la casella non viene letta.

Quindi l'ultimo passo del chiedere è una risposta. Di' a ciascuno che ha chiesto quando la sua richiesta viene rilasciata, con le sue parole, sul canale che ha usato. Chiudere il ciclo di feedback del cliente descrive il meccanismo: la voce di changelog pubblicata è ciò che fa partire il messaggio, così chi ha chiesto viene avvisato solo quando la modifica è online. In Changeloop, quando il feedback del widget è diventato un issue GitHub e la pull request unita lo chiude, approvare la voce pubblica un commento "Shipped" su quell'issue e mostra a chi l'ha inviata la voce nel widget; gli issue aperti a mano e i repository GitLab o Bitbucket non ricevono nessun commento. La nostra documentazione elenca la configurazione di widget e feed.

Una risposta può essere breve: "A marzo avevi chiesto l'import CSV. Oggi è online, ed ecco come funziona." Ti regala anche la domanda successiva migliore: copre quello che ti serviva?

Un piano per cominciare

Scegli un momento dalla tabella in alto, quello in cui gli utenti più spesso riescono o rinunciano. Scrivi una domanda per quel momento, mettila in un solo canale e leggi ogni risposta per due settimane prima di aggiungere una seconda richiesta. Rispondi a chiunque ti abbia dato qualcosa di concreto.

FAQ

Con che frequenza si dovrebbe chiedere feedback ai clienti? Lega le richieste agli eventi, non al calendario. Un utente dovrebbe vedere al massimo una richiesta a settimana, e nessuna subito dopo averne risposto a una. Il messaggio successivo al feedback dovrebbe essere una risposta su cosa ne è stato.

Come si chiede feedback senza infastidire gli utenti? Chiedi dopo un'attività, mai nel mezzo, limitati a una domanda e rendi facile chiuderla. Rispetta una chiusura per qualche settimana.

Conviene offrire un incentivo per il feedback? Di solito non serve. Una domanda specifica e una risposta visibile pesano più di un buono regalo, e gli incentivi attirano chi vuole il premio. Tienili per le interviste, dove chiedi 20 minuti del tempo di qualcuno.

E se nessuno risponde? Restringi la domanda e avvicinala al momento, per esempio a una sola schermata, chiesta subito dopo averla usata. Se resta silenzio, scrivi direttamente a una manciata di utenti e usa quelle conversazioni per scrivere richieste migliori.

Esempi di roadmap di prodotto: sei formati e come falliscono

Fri, 02 Oct 2026 00:00:00 GMT

Gli esempi di roadmap di prodotto che vale la pena copiare rientrano in sei formati: Now/Next/Later, una timeline trimestrale, una roadmap per temi, una per risultati, una roadmap pubblica e una roadmap di rilascio interna. Ognuno risponde a una domanda diversa per un lettore diverso, quindi l'esempio giusto è quello che corrisponde a chi leggerà la tua. L'aspetto grafico è l'ultima cosa da decidere.

Ogni esempio qui sotto riguarda un prodotto inventato, una piccola app di task per team, e ogni voce è inventata. Conta la forma: cosa va in ogni slot, che aspetto ha una voce reale e cosa rompe quel formato dopo un trimestre.

Quali sono dei buoni esempi di roadmap di prodotto?

Un buon esempio di roadmap è breve, nomina un lettore e fa un solo tipo di promessa. Scegli il formato in base alla promessa che sei disposto a mantenere: una direzione, una data, un tema di lavoro, un risultato, un impegno pubblico o un calendario di consegne.

Formato	Pensato per	Funziona quando	Fallisce quando
Now/Next/Later	Tutta l'azienda	I piani cambiano spesso	"Next" si riempie e diventa una coda
Timeline trimestrale	Vendite, supporto, dirigenza	Le date sono vincoli reali	Le date slittano e nessuno le aggiorna
Per temi	Dirigenza, nuovi assunti	Vuoi spiegare il perché	I temi diventano così ampi che ogni voce ci sta
Per risultati	Prodotto e ingegneria	Puoi misurare l'obiettivo	La metrica non ha un responsabile o non ha dati
Pubblica	Clienti	Riesci a tenerla piccola	Diventa una discarica di backlog
Rilascio interno	Ingegneria, QA, supporto	Più team rilasciano insieme	La si scambia per strategia

Che aspetto ha ciascun esempio di roadmap di prodotto?

Ogni formato qui sotto è mostrato con voci realistiche, seguite da chi lo usa, quando regge e come di solito fallisce.

Now/Next/Later

NOW (in costruzione questo mese)
  Viste salvate nella inbox
  Export CSV che funziona sugli account grandi
NEXT (deciso, ordine non fissato)
  SSO per il piano Team
  Notifiche Slack
LATER (una direzione, nessun impegno)
  App mobile
  Audit log

Questo formato va bene per un'azienda che non vuole promettere date, il che vale per molti team nelle prime fasi. Regge perché le tre colonne descrivono quanto sei sicuro: "now" è in corso, "next" è deciso, "later" è una speranza. Fallisce quando "later" diventa il posto dove parcheggiare ogni idea che nessuno vuole rifiutare, e quando "next" acquisisce di nascosto un ordine e una data senza che nessuno lo chiami timeline.

Timeline o roadmap trimestrale

Q4 2026
  Ott   Viste salvate nella inbox
  Nov   SSO beta con cinque design partner
  Dic   SSO disponibilità generale
Q1 2027
  Gen   Notifiche Slack
  Mar   Audit log (solo export)

Serve a vendite, supporto e finanza, che hanno bisogno di pianificare intorno a qualcosa. Funziona quando le date sono vincoli reali, come un contratto, una conferenza o una scadenza di conformità. Fallisce quando le date sono ipotesi, perché un mese in roadmap diventa una promessa in una presentazione commerciale nel giro di poche settimane. Se usi questo formato, etichetta ogni trimestre come impegnato o previsto, e rendi il secondo trimestre visibilmente più morbido del primo.

Roadmap per temi

TEMA: La prima settimana
  Import da CSV e Trello
  Template iniziali
TEMA: Pronti per team più grandi
  SSO
  Audit log
  Permessi per ruolo
TEMA: Meno passaggi manuali
  Notifiche Slack
  Attività ricorrenti

Va bene per gli aggiornamenti alla dirigenza e per i nuovi assunti, perché spiega perché esiste il lavoro prima di elencarlo. Regge quando ogni tema corrisponde a un motivo per cui un cliente ci terrebbe. Fallisce quando i temi sono così larghi ("Crescita", "Qualità") che ogni voce sta sotto ognuno di essi, e a quel punto il raggruppamento non spiega più nulla.

Roadmap per risultati

OBIETTIVO: Più nuovi team completano la configurazione
  Metrica: setup finito entro 7 giorni, dal 40% al 55%
  Scommesse: import da CSV, template iniziali
OBIETTIVO: Meno ticket di supporto sugli export
  Metrica: ticket sugli export a settimana, da 30 a 10
  Scommesse: fix export account grandi, pagina stato export

I numeri sono illustrativi, e il punto è la struttura: un obiettivo, una metrica con un valore di partenza e uno di arrivo, e le scommesse che proverai. Serve ai team di prodotto e ingegneria a cui si lascia scegliere la soluzione. Funziona quando la metrica esiste e qualcuno ne è responsabile. Fallisce quando l'obiettivo non è misurabile, o quando le "scommesse" sono la stessa lista di funzionalità di prima con una frase sul risultato appiccicata sopra.

Roadmap pubblica per i clienti

PIANIFICATO
  Viste salvate nella inbox
IN COSTRUZIONE
  Notifiche Slack
RILASCIATO
  Export CSV per gli account grandi

È il formato più piccolo, e fa la promessa più forte. Serve ai clienti, che vogliono sapere se la loro richiesta è stata ascoltata. Regge con pochissime voci, senza date e con titoli scritti con le parole del cliente. Fallisce come discarica di backlog: ogni "forse" che elenchi è una promessa su cui qualcuno ti chiederà conto più avanti. Come gestirne una a partire dal tuo issue tracker è spiegato in una roadmap pubblica in tre colonne, quindi qui non lo ripetiamo.

Roadmap di rilascio interna

Rilascio	Obiettivo	Responsabile	Dipende da	Stato
5.2	14 ott	Piattaforma	Upgrade del servizio di auth	Codice completo
5.3	11 nov	Inbox	API delle viste salvate	In corso
5.4	9 dic	Piattaforma	Contratto col fornitore SSO	Bloccato

Serve a ingegneria, QA e supporto, che devono sapere cosa esce insieme e cosa blocca cosa. Funziona quando è precisa alla settimana e ogni riga ha un responsabile. Fallisce quando qualcuno la scambia per strategia: un calendario di consegne dice cosa sta uscendo e quando, e non dice nulla sul fatto che quei rilasci fossero le scommesse giuste.

Quale formato di roadmap di prodotto scegliere?

Scegli prima in base al lettore, poi in base a quanta certezza hai davvero. Se non sai dire chi legge la roadmap e quale decisione lo aiuta a prendere, nessuno degli esempi qui sopra la salverà.

Clienti che chiedono "mi avete ascoltato?" Usa il formato pubblico, e tienilo a una manciata di voci.
Vendite e supporto che chiedono "posso dare una data al cliente?" Usa la timeline trimestrale, con impegnato e previsto ben separati.
La dirigenza che chiede "perché questo lavoro?" Usa i temi, o i risultati se hai i dati.
Un team che cambia direzione ogni mese. Usa Now/Next/Later e resisti alla tentazione di datarlo.
Gli ingegneri che chiedono "cosa esce quando?" Usa la roadmap di rilascio, e tienila separata da quella strategica.

La maggior parte dei team finisce con due roadmap: una strategica in una delle prime quattro forme, e sotto un calendario di rilasci. Una roadmap pubblica è allora una vista filtrata di quella strategica, che mostra solo ciò per cui accetti di essere chiamato a rispondere.

Come si scrive una roadmap di prodotto?

Scrivi una roadmap nominando il lettore, scegliendo il formato adatto alla sua domanda, elencando solo le voci che difenderesti in una riunione e dando a ciascuna uno stato e un responsabile. Poi decidi ogni quanto verrà rivista, prima di pubblicarla.

Nomina il lettore e la decisione. "Il supporto decide cosa dire ai clienti sull'SSO" è un motivo. "Tutti dovrebbero vedere la roadmap" non ti dà nulla su cui progettare.
Parti da ciò che già sai. Le richieste aperte, ordinate con una regola che sai spiegare, sono materia prima migliore di un brainstorming.
Scrivi ogni voce come un risultato per il cliente. "Conserva un filtro che usi spesso" si legge meglio di "Implementare la persistenza delle viste salvate", e dice al cliente se il problema è il suo.
Decidi cosa la roadmap non conterrà. Date, stime e un backlog di idee sono le tre esclusioni abituali.
Fissa una data di revisione. Una roadmap senza revisione programmata ha un funerale non programmato.

Come si mantiene aggiornata una roadmap di prodotto?

Mantieni aggiornata una roadmap spostando le voci quando si muove il lavoro, dallo stesso posto in cui il lavoro è tracciato, e registrando cosa è successo quando una voce viene rilasciata o abbandonata. Una roadmap aggiornata a mano in uno strumento separato diventa obsoleta perché non è il lavoro quotidiano di nessuno.

La fonte di verità più economica è l'issue tracker. Se ogni colonna della roadmap corrisponde a un'etichetta sull'issue, la roadmap cambia quando cambia l'etichetta, e nulla viene riscritto. La versione di Changeloop usa le etichette roadmap:planned, roadmap:building e roadmap:shipped, e quando un issue ne porta due vince la più avanzata. Spostare una scheda su rilasciato resta comunque una modifica di etichetta a sé, quindi rendila parte della revisione in cui approvi la voce di changelog.

Quella voce è l'altra metà. Quando una voce viene rilasciata, il changelog dice cosa è cambiato nei termini del cliente, e a chi lo aveva chiesto si può dire che è fatto. Chiudere questo ciclo è lo scopo del ciclo di feedback del cliente, e la roadmap è il tratto di quel ciclo che il cliente può vedere prima che qualcosa venga rilasciato. Se abbandoni una voce, dillo; un "no" pubblico chiude anche quella richiesta, e rifiutare le richieste di funzionalità spiega come formularlo. I team che vogliono vedere come si leggono le voci finite possono sfogliare gli esempi di changelog.

FAQ

Qual è il formato di roadmap di prodotto più semplice? Now/Next/Later. Ha tre colonne, non richiede date e raggruppa le voci per grado di certezza. Per un piccolo team che cambia direzione spesso, è anche il formato in cui è più difficile fare una figuraccia.

Quante voci dovrebbe avere una roadmap di prodotto? Meno di quante pensi. Meno di dieci su tutte le colonne bastano per una roadmap pubblica, e una strategica interna raramente ne richiede più di una dozzina. Oltre, è un backlog con un'intestazione più carina.

Una roadmap di prodotto dovrebbe includere delle date? Solo se le date sono vincoli reali, e in quel caso solo per il trimestre più vicino. Oltre, usa colonne o temi. Una data in roadmap diventa un impegno in una trattativa commerciale, che tu lo voglia o no.

Qual è la differenza tra una roadmap di prodotto e un piano di rilascio? La roadmap dice cosa intendi costruire e perché. Il piano di rilascio dice quale build esce in quale data e chi ne è responsabile. La roadmap cambia quando cambia la strategia, e il piano di rilascio cambia quando cambia il lavoro.

Processo di release management per chi rilascia spesso

Fri, 02 Oct 2026 00:00:00 GMT

Un processo di release management è l'insieme dei passi che porta una modifica da "integrata" a "in esecuzione in produzione e spiegata alle persone che riguarda". Per un team che rilascia spesso si riduce a sette passi: pianificare l'ambito, isolare la modifica, compilare e testare, approvare, rilasciare e verificare, comunicare, e fare la revisione. Ogni passo ha bisogno di un responsabile con nome e di un criterio di uscita, altrimenti smette di accadere senza che nessuno se ne accorga.

Questa guida presuppone un team da 5 a 50 ingegneri che rilascia ogni settimana o ogni giorno e vuole che il processo non intralci.

Passo	Responsabile	Criteri di uscita
1. Pianificare l'ambito	Product o tech lead	L'elenco delle modifiche di questo rilascio è scritto, e ciò che è rischioso è segnato
2. Branch o flag	L'ingegnere che possiede la modifica	Il lavoro è su un branch di breve durata o dietro un flag, così main resta rilasciabile
3. Build e test	La CI, con l'autore reperibile per i fallimenti	Pipeline verde sul commit esatto che verrà rilasciato
4. Approvare	Revisore, più il release manager per le modifiche rischiose	Revisione fatta, percorso di rollback nominato, go o no-go registrato
5. Deploy e verifica	Release manager o ingegnere di turno	Rilasciato, smoke check superati, tasso di errori e latenza in linea con la baseline pre-rilascio
6. Comunicare	Chi capisce la modifica, rivisto da qualcuno che non la capisce	Release notes pubblicate dove gli utenti le leggono, supporto e vendite avvisati
7. Revisione	Release manager	Metriche lette, ciò che è andato storto ha un responsabile e una correzione

Cos'è il processo di release management?

È il percorso ripetibile che una modifica segue per raggiungere gli utenti: ambito, build, test, approvazione, deploy, verifica, annuncio e bilancio finale. Il senso di metterlo per iscritto è che ogni rilascio segue lo stesso percorso, così una persona in ferie, un nuovo assunto o un ingegnere di turno alle 2 di notte può eseguirlo senza chiedere a nessuno come funziona.

Quali sono i diversi tipi di release management?

Ci sono tre tipi pratici: deploy continuo, rilasci programmati e gestione del cambiamento regolamentata. Si differenziano per quanto accade prima di un rilascio e quanto è automatizzato. Il deploy continuo rilascia ogni modifica integrata, i rilasci programmati raggruppano le modifiche in un treno, e la gestione del cambiamento regolamentata aggiunge approvazione formale e una traccia di audit.

	Deploy continuo	Rilasci programmati	Gestione del cambiamento regolamentata o ITIL
Unità di rilascio	Una pull request integrata	Un lotto, settimanale o quindicinale	Una richiesta di cambiamento
Passo dell'ambito	Implicito, l'integrazione è l'ambito	Riunione di pianificazione del rilascio	Record di cambiamento con valutazione del rischio
Approvazione	Code review più controlli automatici	Il release manager approva il lotto	Change advisory board o approvatore delegato
Controllo del rischio	Feature flag, canary, rollback rapido	Soak in staging, release candidate	Piano di backout documentato, finestra di manutenzione
Cadenza tipica	Molti al giorno	Da settimanale a mensile	Stabilita dal calendario dei cambiamenti
Punto debole	Nessuno dice agli utenti cosa è cambiato	I lotti grandi nascondono la modifica che ha rotto qualcosa	Il tempo di processo supera di molto la modifica stessa

La maggior parte dei team è un misto. Un prodotto SaaS può fare deploy continuo mentre la sua app mobile esce con un treno settimanale, e l'unico servizio di pagamenti che interessa ai revisori segue un record di cambiamento formale. Scegli il tipo per servizio, non per azienda. Dove le modifiche vengono esposte gradualmente, rilascio e annuncio diventano eventi separati, come nel caso trattato in release notes con feature flag.

Quali sono le responsabilità di un release manager?

Un release manager possiede il percorso che una modifica compie fino alla produzione. Tiene il calendario dei rilasci, decide se una modifica è pronta, esegue o supervisiona il deploy, prende la decisione sul rollback, si assicura che gli utenti siano avvisati e conduce la revisione successiva.

Prima del rilascio, conferma l'ambito e controlla che ogni modifica rischiosa abbia un percorso di rollback. Durante, esegue la checklist di deploy, osserva i primi minuti di metriche di produzione e decide presto un rollback. Dopo, conferma che le note siano uscite e registra cosa correggere nel processo.

In un team piccolo, ruota il ruolo ogni settimana e scrivi la checklist in modo che nessuno abbia bisogno di conoscenze tramandate a voce. Un monorepo con molti pacchetti rilasciati in modo indipendente di solito richiede un responsabile del rilascio per pacchetto, altrimenti il ruolo diventa un collo di bottiglia.

Quali sono i KPI chiave per il release management?

Segui le metriche di delivery del software DORA, e aggiungine una tua: quanto tempo passa prima che gli utenti vengano avvisati. La ricerca DORA individua cinque metriche, divise in throughput (tempo di consegna delle modifiche, frequenza di deploy, tempo di ripristino da deploy fallito) e instabilità (tasso di fallimento delle modifiche, tasso di rilavorazione dei deploy).

La guida DORA le definisce in termini semplici (dora.dev, software delivery metrics):

KPI	Cosa misura	A cosa fare attenzione
Tempo di consegna delle modifiche	Tempo dal commit nel controllo di versione al deploy in produzione	Un numero in crescita di solito indica code in revisione o approvazione
Frequenza di deploy	Quanto spesso fai deploy, o il tempo tra un deploy e l'altro	Una frequenza in calo significa che i lotti stanno crescendo
Tempo di ripristino da deploy fallito	Tempo per riprendersi da un deploy che richiede intervento immediato	Qui emergono i problemi di rollback e di allerta
Tasso di fallimento delle modifiche	Quota di deploy che richiedono un rollback o un hotfix	Sale quando i lotti sono troppo grandi o i test sono scarsi
Tasso di rilavorazione dei deploy	Quota di deploy non pianificati e causati da un incidente in produzione	Un segno che le correzioni escono più in fretta delle lezioni
Tempo prima che gli utenti siano avvisati	Minuti dal deploy in produzione a una nota pubblicata per gli utenti	Misuralo tu, nessun framework lo fornisce

Il materiale più vecchio elenca quattro metriche chiave e chiama il ripristino "time to restore". La guida attuale usa le cinque qui sopra.

La stessa guida avverte di non trattarle come obiettivi. Fissare un traguardo come "tutto viene rilasciato più volte al giorno entro fine anno" invita i team a truccare i numeri, e le metriche vanno lette per applicazione o servizio, non mescolate su tutta l'azienda. Il suo consiglio pratico per migliorarle tutte è ridurre la dimensione di ogni modifica, perché le modifiche più piccole sono più facili da rivedere, da far passare nella pipeline e da cui riprendersi.

Come si inserisce la comunicazione dei rilasci nel processo di release management?

È il passo sei, e ha un responsabile e un criterio di uscita come ogni altro passo: note pubblicate dove gli utenti le leggono, e team interni avvisati. È il passo che i team saltano più spesso, perché gli strumenti di deploy segnalano il successo nel momento in cui il codice è online.

Il modo più economico per tenere questo passo in orario è scrivere la voce quando la modifica viene integrata, non quando il rilascio esce. La pull request contiene già il titolo, l'autore, l'issue collegato e il contesto. Una bozza costruita da lì viene rivista, non scritta a memoria una settimana dopo. È l'idea dell'automazione del changelog: ricavare una bozza all'integrazione, tenerla in attesa di approvazione umana, poi pubblicarla ovunque da un'unica fonte. Changeloop funziona così, preparando le voci dalle pull request integrate con l'AI e tenendole in attesa di approvazione prima che venga pubblicato qualcosa.

Vale la pena pianificare in anticipo due varianti. Supporto e vendite hanno bisogno di una nota diversa da quella per i clienti, ed è a questo che servono le release note interne. Un rilascio guidato da un incidente non ha tempo per il normale ciclo di redazione, quindi tieni pronto un breve template, come descritto nelle release notes di emergenza. Il template di release notes ti dà una forma di partenza per la versione rivolta ai clienti.

Come si mantiene leggero il processo?

Automatizza ogni criterio di uscita che una macchina può controllare, e lascia agli umani i giudizi. Una pipeline verde, un marcatore di deploy sulle dashboard e una bozza di voce di changelog per ogni pull request integrata sono verificabili. Stabilire se un piano di rollback è credibile, o se le note hanno senso per un cliente, richiede una persona.

Per mettere alla prova il processo, scegli un rilascio del mese scorso e chiediti se qualcuno fuori dal team potrebbe capire, dalla sola documentazione scritta, cosa è stato rilasciato, chi l'ha approvato, come è stato verificato e quando gli utenti sono stati avvisati. Ogni lacuna è il tuo prossimo miglioramento.

FAQ

Qual è la differenza tra release management e change management? Il release management porta un insieme di modifiche a essere compilate, testate, rilasciate e annunciate. Il change management, in senso ITIL, è il processo di approvazione e di rischio attorno a ogni modifica. I team che rilasciano spesso fondono l'approvazione nella code review e nei controlli automatici.

Con che frequenza dovremmo rilasciare? Con la frequenza che i vostri test e il percorso di rollback permettono, che per molti team web è ogni giorno o più. L'indicazione di DORA è ridurre la dimensione di ogni modifica, perché le modifiche piccole sono più facili da rivedere e da cui riprendersi.

I team piccoli hanno bisogno di un release manager? Hanno bisogno delle responsabilità, ma non necessariamente del titolo. Fai ruotare il ruolo tra gli ingegneri, dai alla persona di turno una checklist scritta e assicurati che qualcuno sia responsabile di ciascuno dei sette passi.

Cosa dovrebbe includere una checklist di rilascio? Ambito confermato, pipeline verde sul commit da rilasciare, percorso di rollback nominato, approvazione registrata, smoke check dopo il deploy, metriche confrontate con la baseline, release notes pubblicate, supporto avvisato e una revisione in calendario. Tienila a una pagina.

Esempi di release notes per ogni tipo di modifica

Fri, 02 Oct 2026 00:00:00 GMT

I migliori esempi di release notes sono brevi, dicono chi è interessato e cosa fare dopo. Qui sotto c'è un esempio per ogni tipo di modifica che rilascerai, con il motivo per cui funziona, così puoi copiare la forma e sostituire i tuoi fatti.

Ogni esempio è inventato, per un'app di fatturazione fittizia chiamata Tidepool.

Cosa hanno in comune dei buoni esempi di release notes?

Dicono agli utenti cosa è cambiato e cosa, se serve, devono fare, con le parole degli utenti. Ogni tipo di modifica ha un compito diverso, quindi la forma cambia dall'una all'altra.

Tipo di modifica	La voce deve dire	Dove va
Nuova funzionalità	Cosa può fare ora il lettore, e chi la riceve	In cima alle note
Miglioramento	Cosa è diventato più veloce o facile, con un numero se ce l'hai	Dopo le funzionalità
Correzione di bug	Il sintomo che il lettore ha visto, e che è risolto	Dopo i miglioramenti
Breaking change	Chi è interessato, la data, la migrazione	Per prima, sempre
Fix di sicurezza	Cosa era esposto, se è stato sfruttato, cosa fare	Per prima
Deprecazione	Cosa sparisce, la data di fine, il sostituto	Vicino alla cima
Nota per l'app store	Una frase semplice per modifica, entro il limite di caratteri	Scheda dello store
Nota interna	Cosa è cambiato e cosa dire ai clienti	Canali di supporto e vendite

Che aspetto ha una buona nota per una nuova funzionalità?

Una buona nota di funzionalità apre con ciò che il lettore può fare ora e nomina i piani o i ruoli che la ricevono. Salta l'implementazione.

Invia le fatture nella lingua del cliente. Ora puoi scegliere una lingua per ogni cliente, e le sue fatture, i solleciti e la pagina di pagamento la seguono. Francese, tedesco, spagnolo e portoghese sono disponibili su tutti i piani. Impostala nella pagina del cliente, sotto Preferenze di fatturazione.

Il titolo è una frase che il lettore direbbe a voce alta, e il corpo dà ambito e posizione. Un lettore che scorre solo la riga in grassetto sa comunque cosa è stato rilasciato. Il metodo più ampio è in come scrivere release notes.

Che aspetto ha una buona nota di miglioramento?

Una nota di miglioramento descrive un cambiamento che il lettore sentirà, e mette un numero misurato quando esiste. Senza numero, di' cosa il lettore non deve più fare.

L'elenco delle fatture si carica circa tre volte più in fretta. Gli account con più di 5.000 fatture aspettavano circa nove secondi per l'elenco. Ora si apre in circa tre. Nessuna azione necessaria.

"Miglioramenti delle prestazioni" non dice niente al lettore, mentre nove secondi contro tre è un'affermazione che può verificare lunedì mattina. Il "Nessuna azione necessaria" finale risponde alla domanda che ogni lettore si fa.

Che aspetto ha una buona nota di correzione di bug?

Una nota di correzione descrive il sintomo che l'utente ha visto, non la causa nel codice, e dice se deve rifare qualcosa. Le correzioni che nessuno ha notato possono andare nell'elenco in fondo.

Corretto: email di sollecito inviate due volte alla scadenza. Alcuni clienti ricevevano due solleciti identici se la fattura scadeva l'ultimo giorno del mese. Il problema è risolto. I solleciti già inviati non sono interessati, e nessuno deve rinviare nulla.

Il titolo inizia con "Corretto" così chi scorre può smistarlo a colpo d'occhio, e la condizione reale (l'ultimo giorno del mese) segue subito.

Come si scrivono le release notes per una breaking change?

La nota di una breaking change apre con la data e il gruppo interessato, poi dà la migrazione nella stessa voce. Va per prima nelle release notes, perché è l'unica voce che un lettore non deve perdere.

Le firme dei webhook diventano obbligatorie il 1° dicembre 2026. Da quella data Tidepool smette di inviare payload webhook non firmati. Riguarda chi riceve webhook senza controllare l'header Tidepool-Signature. Per migrare, verifica l'header con il segreto che trovi in Impostazioni, Sviluppatori. Se verifichi già le firme, nessuna azione necessaria.

La data è nel titolo, quindi sopravvive a una lettura veloce. Il gruppo interessato è nominato per ciò che fa, e l'ultima frase libera chi è già a posto, il che riduce il carico sul supporto. La guida alle breaking changes spiega come decidere se una modifica conta.

Che aspetto ha una nota su un fix di sicurezza?

Una nota di sicurezza dice cosa era esposto, se qualcuno l'ha sfruttato, chi è interessato e cosa deve fare. Resta fattuale e calma.

Sicurezza: i link di reimpostazione della password potevano essere riutilizzati. Tra il 3 e il 17 settembre 2026, un link di reimpostazione della password restava valido dopo essere stato usato una volta. Non abbiamo trovato segni di sfruttamento. Il problema è risolto, e tutti i link di reimpostazione in sospeso sono stati invalidati. Se hai richiesto una reimpostazione in quel periodo, richiedi un nuovo link.

La finestra esatta permette al lettore di valutare la propria esposizione, e la frase sullo sfruttamento risponde alla prima domanda che chiunque si fa. "Un potenziale problema" suona come un tentativo di nascondere, quindi di' ciò che sai.

Come si scrive un avviso di deprecazione?

Un avviso di deprecazione nomina ciò che viene rimosso, dà una data di fine ferma e indica il sostituto.

L'endpoint v1 delle fatture è deprecato e termina il 1° marzo 2027. GET /v1/invoices continua a funzionare fino al 1° marzo 2027, poi restituisce 410 Gone. Usa GET /v2/invoices, che restituisce gli stessi campi più currency. Le risposte di v1 ora includono un header Sunset con la data di fine. Una guida di migrazione affiancata è nella documentazione.

Il nome dell'endpoint è nel titolo, perché chi è interessato lo cerca, e il sostituto sta accanto alla rimozione. L'header Sunset dice agli sviluppatori quali chiamate usano ancora la vecchia versione. Il trattamento più lungo è in deprecare un'API.

Che aspetto ha una nota di rilascio per l'app store?

Una nota per l'app store è fatta di due o tre frasi semplici, perché la maggior parte delle persone legge solo la prima riga. Apri con la modifica che un utente noterebbe.

Scansiona una ricevuta cartacea e Tidepool compila importo, data e fornitore. La modalità scura ora segue l'impostazione del telefono. Abbiamo anche corretto un arresto anomalo all'apertura di una fattura da una notifica.

La modifica più utile viene per prima, e la correzione nomina la situazione che causava il crash. Niente numero di versione e niente "correzioni di bug e miglioramenti". Release notes per app mobile spiega le regole specifiche degli store.

Cosa dovrebbe includere una nota di rilascio interna?

Una nota interna è la versione per supporto e vendite. Aggiunge ciò che la nota pubblica lascia fuori: cosa dire, e cosa evitare di promettere.

Le fatture multilingua sono uscite oggi (tutti i piani). Supporto: i clienti impostano la lingua sotto Preferenze di fatturazione, e le fatture esistenti mantengono la lingua originale. L'italiano non è ancora disponibile. Vendite: è aperta a ogni piano, quindi non presentarla come un upgrade.

Ogni pubblico ha la sua riga etichettata, e la nota traccia il confine ("L'italiano non è ancora disponibile") prima che un cliente lo chieda. L'articolo sulle release note interne spiega formato e canali.

Che aspetto ha una brutta release note, riscritta?

Una brutta release note elenca ciò che ha fatto il team invece di ciò che ottiene il lettore. Si corregge spostando il risultato in testa e togliendo il vocabolario interno.

Prima:

v3.8.1 Rifattorizzato lo scheduler dei solleciti. Corretta una race condition in ReminderJob. Aggiornato bull a 4.12. Miglioramenti vari.

Dopo:

Le email di sollecito non partono più due volte. I clienti con una fattura in scadenza l'ultimo giorno del mese potevano ricevere due solleciti. Il problema è risolto, e i solleciti già inviati non vanno rinviati. Nessuna azione necessaria.

Anche nella 3.8.1: bull aggiornato a 4.12.

L'aggiornamento della dipendenza è sceso in una riga a piè di pagina, e la race condition è diventata un sintomo che un cliente riconoscerebbe.

Come si mantengono coerenti le release notes tra un rilascio e l'altro?

Scrivi ogni voce quando la modifica viene integrata, e fai approvare da una persona prima che esca.

Changeloop funziona così: prepara una bozza di voce da ogni pull request integrata usando l'AI e la tiene in attesa finché una persona la approva. Il passaggio di approvazione è il punto in cui un editor applica le regole qui sopra. Per stabilire prima il formato, parti dal template di release notes, e guarda gli esempi di changelog per vedere come sono fatte le pagine finite.

FAQ

Cosa sono le nuove release notes? Le nuove release notes sono il messaggio pubblicato con l'ultimo rilascio di un prodotto, che descrive cosa è cambiato e cosa devono fare gli utenti. Coprono funzionalità, miglioramenti, correzioni e breaking changes.

Qual è la differenza tra una release note e un changelog? Il changelog tiene tutto, per chiunque voglia la storia intera. Una release note sceglie da lì: un solo rilascio, scritto per i lettori che stanno decidendo se li riguarda. Il confronto completo è in changelog vs release notes.

Cosa significa release notes? Le release notes dicono agli utenti cosa è cambiato in un rilascio. L'espressione copre qualsiasi cosa che spiega cosa è stato rilasciato, dal testo "Novità" di un app store a una pagina sul sito di un'azienda.

Quanto deve essere lunga ogni voce delle release notes? Da due a quattro frasi bastano per la maggior parte delle voci: il risultato, chi è interessato e cosa fare. Una breaking change o un fix di sicurezza possono essere più lunghi perché richiedono una data o una migrazione.

Versionamento API di Stripe: come funziona e cosa copiare

Fri, 02 Oct 2026 00:00:00 GMT

Il versionamento API di Stripe funziona per data. Ogni account è fissato a una versione dell'API che prende il nome da una data di rilascio, e ogni singola richiesta può scavalcare quel valore con un header Stripe-Version. Al momento della scrittura (ottobre 2026), la versione corrente nella documentazione di Stripe è 2026-09-30.endive, e lo stesso schema è qualcosa che un'API molto più piccola può copiare in un fine settimana.

Ogni fatto su Stripe qui sotto viene dalle pagine di Stripe stessa, collegate dove vengono usate.

Meccanismo	Cosa fa Stripe	Fonte
Nome della versione	Una data, più un nome di rilascio dal 2024 (`2026-09-30.endive`)	Versioning
Versione predefinita	Fissata sull'account, cambiata in Workbench	Versioning
Override per richiesta	Header `Stripe-Version`, o l'opzione dell'SDK	Upgrades
Webhook	Resi nella versione impostata sull'endpoint	Upgrades
Cadenza	Rilasci mensili senza breaking changes, una major due volte l'anno	Versioning
Vecchie versioni	Mantenute funzionanti con moduli interni di cambio versione	Engineering post

Come funziona il versionamento API di Stripe?

Stripe dà a ogni account una versione API predefinita, e ogni richiesta che non nomina una versione usa quella. Chi chiama sceglie quando passare, cambiando il valore predefinito o impostando una versione sulle singole richieste.

Il post di engineering di Stripe dice che l'account viene fissato la prima volta che fa una richiesta API: l'account è "automatically pinned to the most recent version available", e da lì ogni chiamata riceve implicitamente quella versione.

La stringa di versione è una data. Dal rilascio 2024-09-30.acacia porta anche un nome, come in 2026-09-30.endive. La data ordina le versioni, e il nome dice a quale famiglia di rilasci major appartiene una versione.

Come si sceglie una versione per ogni richiesta?

Invia l'header Stripe-Version sulla richiesta, oppure imposta la versione nell'SDK. La guida all'upgrade di Stripe mostra la forma con l'header, e la stessa chiamata funziona negli ambienti live e di test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

La guida di Stripe osserva che quando imposti la versione a livello globale o per richiesta in un SDK, gli oggetti di risposta tornano in quella versione.

Stripe sconsiglia anche di appoggiarsi al valore predefinito dell'account. Nelle sue parole, specifica la versione per ogni richiesta, con l'header o con un SDK bloccato, così che sia il tuo codice a decidere la versione e non un'impostazione della dashboard.

Gli SDK fissano la versione in modo diverso a seconda del linguaggio. La documentazione dice che le versioni recenti delle librerie a tipizzazione dinamica usano la versione API che era l'ultima quando è uscita quella release dell'SDK, mentre quelle fortemente tipizzate (Java, Go e .NET) sono ancorate a essa. Installare una versione della libreria significa, di fatto, scegliere una versione API.

Cosa succede ai webhook quando cambia la versione?

Un evento webhook viene reso nella versione API associata al suo endpoint, non nella versione che usa il codice del tuo server. La documentazione di Stripe dice che gli eventi usano la versione impostata alla creazione dell'endpoint, e altrimenti quella predefinita dell'account. Cambiare la versione del tuo SDK non cambia ciò che riceve il tuo gestore webhook.

Il percorso delle richieste e quello degli eventi possono quindi trovarsi su due versioni diverse. Per le destinazioni degli eventi, imposti snapshot_api_version solo quando crei la destinazione, quindi una versione diversa richiede una nuova destinazione.

Il percorso di upgrade di Stripe per questo è un'esecuzione in parallelo. Crea un nuovo endpoint alla versione di destinazione, invia gli stessi eventi a entrambi, insegna al gestore a elaborarne uno e a ignorare l'altro, poi passa e disattiva il vecchio endpoint. Poiché durante la sovrapposizione ogni evento arriva due volte, il gestore deve essere idempotente. È un buon schema da copiare per qualsiasi API che emette eventi, e un changelog dei webhook è il posto dove annunciare le modifiche ai payload che lo rendono necessario.

Cosa sono i rilasci mensili e major?

Dal rilascio 2024-09-30.acacia, Stripe pubblica una nuova versione dell'API ogni mese senza breaking changes, ed emette una nuova major due volte l'anno che parte con una versione contenente breaking changes. La sua pagina sul versionamento dice che puoi passare a qualsiasi rilascio mensile senza aggiornare il codice, mentre una major può richiedere modifiche.

Le major hanno dei nomi. La pagina sul versionamento fa l'esempio di Basil, e l'annuncio del processo da parte di Stripe dice che i nomi vengono dalle piante, a partire da Acacia, e che i rilasci mensili mantengono il nome della major precedente, così il nome segnala che si può passare in sicurezza. Il changelog di Stripe elenca i nomi in uso, e al momento della scrittura la voce più recente è 2026-09-30.endive.

Quindi la data risponde a "quanto è nuova", e il nome risponde a "è un confine di breaking change". L'annuncio di Stripe lascia anche spazio a eccezioni: si riserva il diritto di rilasciare una breaking change fuori ciclo dove un'integrazione sarebbe gravemente colpita senza di essa. L'annuncio è in Stripe's new API release process.

Qual è l'ultima versione dell'API di Stripe?

Al momento della scrittura (ottobre 2026), la pagina di Stripe sul versionamento indica che la versione corrente è 2026-09-30.endive, e il suo changelog elenca la stessa versione come la più recente. Stripe pubblica una nuova versione ogni mese, quindi qualsiasi stringa stampata in un articolo invecchia in fretta. Leggi il changelog aggiornato prima di fissare qualcosa, e fissa la versione con cui hai testato.

Come fa Stripe a mantenere funzionanti le vecchie versioni?

Stripe mantiene vive le vecchie versioni scrivendo ogni breaking change come un modulo di cambio versione autonomo e applicando i moduli all'indietro a partire dalla forma più recente dei dati. Il suo post di engineering sul versionamento API descrive il meccanismo.

Ogni modulo dichiara cosa cambia, documenta la modifica e include una funzione di trasformazione. Il post fa l'esempio di un campo che passa da stringa a hash. Per costruire una risposta, il sistema determina la versione di destinazione, poi risale nel tempo e applica ogni modulo che trova lungo la strada fino a raggiungere quella versione.

Da questa progettazione seguono due effetti collaterali, e il post nomina entrambi. Poiché i moduli dichiarano i campi e le risorse che toccano, Stripe può generare il proprio changelog API da essi al momento del deploy. E poiché la versione dell'account è nota, la documentazione può adattarsi a essa e avvisare delle modifiche incompatibili dall'ultima versione usata.

Quanto costa, e cosa dovrebbe copiare un'API più piccola?

Il versionamento costa attenzione ingegneristica, e Stripe lo dice. Il post di engineering riconosce un onere di manutenzione e indica l'obiettivo: meno bisogna pensare al vecchio comportamento quando si scrive nuovo codice, meglio è. Descrive anche revisioni leggere dell'API prima del rilascio, per evitare di dover cambiare versione.

Un'API piccola non può permettersi una catena di moduli per ogni vecchia versione, e non ne ha bisogno. Copia le parti che portano valore:

Versioni datate. Una data non richiede di giudicare cosa conti come "major", e chi chiama la può leggere. L'articolo sulle buone pratiche di versionamento la confronta con gli schemi a URL e a header.
Un valore predefinito fissato. Fissa l'account o la chiave alla versione del primo uso, così l'API non cambia sotto un'integrazione funzionante.
Un override per richiesta. Un header che permette a chi chiama di testare una nuova versione su una sola chiamata, in produzione, prima di impegnarsi.
Una versione sull'endpoint dei webhook. I payload degli eventi sono il punto in cui chi chiama si sorprende di più.
Una voce di changelog per versione. Fai in modo che nomini la versione, la data, chi è interessato e cosa fare. Cosa conta come breaking è il test per decidere cosa appartiene a una nuova versione, e l'articolo sul changelog API copre la voce in sé.

Salta la catena di moduli finché il numero di versioni supportate non la impone. Due o tre versioni attive si gestiscono con qualche ramo e una data di sunset, come spiega dismettere una versione API.

Se pubblichi un changelog datato, la cronologia delle versioni vale quanto le sue voci. In Changeloop, una bozza di voce viene creata da ogni pull request integrata e tenuta in attesa finché una persona la approva, prima di pubblicarla nella pagina del changelog e nel feed. È lì che si scrive la voce per versione, e l'unico controllo umano è la revisione che dice cosa deve fare chi chiama.

FAQ

Qual è l'ultima versione dell'API di Stripe? Al momento della scrittura (ottobre 2026), la pagina di Stripe sul versionamento indica che la versione corrente è 2026-09-30.endive. Stripe emette una nuova versione ogni mese, quindi controlla il suo changelog prima di fissarla, e scrivi la versione nel tuo codice invece di affidarti al valore predefinito dell'account.

Come imposto la versione dell'API di Stripe su una richiesta? Invia l'header Stripe-Version, per esempio Stripe-Version: 2026-09-30.endive, oppure imposta la versione nel tuo SDK lato server, a livello globale o per richiesta. Senza nessuno dei due, una richiesta usa la versione predefinita del tuo account, che imposti in Workbench.

I webhook usano la stessa versione dell'API di Stripe delle mie richieste? Non necessariamente. Gli eventi webhook usano la versione impostata alla creazione dell'endpoint, e quella predefinita dell'account se non ne è stata impostata una. Aggiornare l'SDK non cambia il payload che riceve il tuo gestore webhook, quindi aggiorna gli endpoint separatamente e testali in parallelo.

Il versionamento per data in stile Stripe va bene per una piccola API? Versioni datate, un valore predefinito fissato, un header per richiesta e una voce di changelog per versione costano poco e vale la pena copiarli. La catena interna di moduli di cambio versione no, finché non supporti molte vecchie versioni insieme. Parti con due versioni attive e una data di sunset per la più vecchia.

Chi scrive il changelog, e chi dovrebbe

Tue, 22 Sep 2026 00:00:00 GMT

Chiedete a un team chi scrive il changelog e la risposta onesta di solito è "chiunque se ne ricordi", che è la stessa modalità di fallimento che imporre una voce di changelog in CI esiste per risolvere a livello meccanico. Ma forzare l'esistenza di una voce non decide chi è qualificata a scriverne una buona, e i team che saltano quella domanda tendono a ripiegare su chiunque sia più facile da obbligare, di solito chi apre la PR, senza controllare se quella sia davvero la persona che può scriverla bene.

Perché chi apre la PR non è automaticamente chi scrive meglio il changelog?

Perché conosce l'implementazione, non necessariamente l'impatto, e sono due tipi di conoscenza diversi. Dove si fermano i conventional commit copre questo divario dal lato del messaggio di commit: fix(auth): reject expired refresh tokens è corretto e inutile per una cliente, e chi ha scritto quella correzione è spesso la persona meno attrezzata per tradurla, perché ha pensato in termini del bug per ore e ha perso la visuale esterna di cosa un'utente abbia effettivamente vissuto. È la stessa ragione per cui le tecniche di scrittura esistono come professione: tradurre l'implementazione in impatto è un'abilità distinta dall'aver costruito la cosa, e serve pratica indipendentemente da quanto sia brava la sviluppatrice nel codice in sé.

Questo significa che prodotto o supporto dovrebbero scrivere ogni voce al posto loro?

No, perché hanno il divario opposto: sanno cosa conta per le utenti ma non sempre cosa è stato davvero rilasciato, il che produce voci leggibili ma occasionalmente sbagliate nell'ambito, un "ora supporta X" per una funzionalità ancora dietro un flag, o una correzione descritta come completa quando copre solo uno di tre casi. La modalità di fallimento delle voci scritte da sviluppatrici è illeggibile-ma-accurata; la modalità di fallimento delle voci scritte da PM è leggibile-ma-non-verificata. Nessun ruolo possiede entrambe le metà di ciò di cui ha bisogno una buona voce.

Ruolo	Di solito azzecca	Di solito sbaglia
Sviluppatrice che ha scritto il codice	Ambito esatto di cosa è cambiato	Inquadrarlo per chi non l'ha costruito
PM o responsabile del supporto	Perché conta per l'utente	Confini precisi di cosa è davvero stato rilasciato
Responsabile dedicata del changelog	Voce coerente, verifica l'ambito	Ha bisogno di entrambe le precedenti per verificare

Come appare davvero un modello di proprietà che funziona?

Una bozza da chi è più vicino al cambiamento, revisionata da chi è più vicino all'utente, con una persona nominata responsabile della formulazione finale invece che tutti assumano che qualcun altro catturerà i problemi. La bozza deve esistere ed essere accurata più di quanto debba essere buona; una frase grezza scritta da una sviluppatrice che dice correttamente cosa è cambiato è un punto di partenza migliore di una levigata ma non verificata, perché riscrivere per chiarezza è più facile che riscrivere per correttezza. Il passaggio di revisione è dove una PM o responsabile del supporto legge la bozza e fa l'unica domanda che cattura il divario di leggibilità: lo capirei se non avessi visto il codice.

Dovrebbe essere sempre la stessa persona quella responsabile, o ruota?

Nominata e stabile batte rotante, almeno per l'approvazione finale. Una responsabile rotante significa che ogni voce viene revisionata da qualcuno che ri-deriva da zero le convenzioni del team, il che è esattamente come la voce deriva da una voce all'altra e chi legge inizia a notare che il changelog è stato scritto da un comitato. Una singola persona, o un gruppo stabile molto piccolo, accumula nel tempo i giudizi, quando dire "migliorato" invece di nominare la cifra specifica, quando una correzione ha bisogno di una propria voce invece di confluire in un lotto, e quel giudizio vale più della distribuzione uniforme del lavoro.

Bozza (sviluppatrice, dalla PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisionata (responsabile del changelog, verificata contro la PR reale):
"Corretto: le esportazioni ordinate per data potevano
restituire risultati fuori ordine oltre la prima pagina.
Ora coerente su tutte le pagine."

Un piccolo team ha bisogno di così tanto processo per una riga di testo?

Non i ruoli come persone separate, ma i due passaggi contano ancora anche in solitaria. Un team di una persona è sia la sviluppatrice sia la revisora, e la disciplina che sopravvive a quella scala è fare la revisione come un passaggio mentale separato, non saltare direttamente dallo scrivere la correzione al pubblicarne una descrizione nello stesso respiro. La trappola su piccola scala è saltare del tutto il secondo passaggio, non la mancanza di una seconda persona, perché nessuno esterno lo impone, e il divario di accuratezza che quel passaggio esiste per catturare non scompare solo perché la stessa persona potrebbe teoricamente notare il proprio punto cieco.

Cosa succede quando nessuno è responsabile della voce finale?

Il changelog degrada in modo irregolare invece di fallire apertamente, il che è peggio perché nessuno se ne accorge finché una lettrice non lo segnala. Alcune voci restano nitide perché a chi le ha scritte importava; altre diventano vaghe, "vari miglioramenti e correzioni di bug", perché chi le ha scritte andava veloce e nessuno l'ha notato prima della pubblicazione. I vincoli di formato di Keep a Changelog catturano la deriva strutturale, date mancanti, categorie sbagliate, ma niente in un template cattura una voce vaga che è tecnicamente ben formattata, che è esattamente il divario che una responsabile nominata è lì per colmare.

FAQ

La responsabile del changelog dovrebbe essere un ruolo di ingegneria o di prodotto? Entrambi possono funzionare se la persona ha sia fluidità tecnica per verificare l'ambito sia abbastanza distanza dall'implementazione per scrivere per una lettrice esterna; il titolo conta meno di se sappia fare entrambe le metà, o sappia a chi chiedere per la metà che non sa fare.

Un programma rotante tipo reperibilità è mai appropriato per la proprietà del changelog? Per il volume, a volte, se il team è troppo piccolo perché una persona revisioni tutto; per voce e giudizio, no, perché è esattamente ciò che la rotazione erode. Una rotazione che condivide il carico di stesura mantenendo una revisora stabile ottiene il beneficio senza la deriva.

Qual è il segno più veloce che qualcosa non va nell'attuale configurazione di proprietà? Voci che sono accurate ma illeggibili, o leggibili ma sbagliate nell'ambito, in uno schema che segue chi le ha scritte. Se la qualità correla con l'autrice invece di restare coerente, la proprietà è il divario, non l'abilità di scrittura.

L'automazione riduce quanto conta la proprietà? Riduce quanta scrittura serve, non quanto giudizio serve. Automazione del changelog copre cosa una pipeline può generare in sicurezza, formattazione, pubblicazione, cross-posting; la formulazione, il raggruppamento e cosa conta come degno di menzione restano decisioni umane indipendentemente da quanto della pipeline sia automatizzata.

Cosa succede se l'autrice della PR e la revisora non sono d'accordo sulla formulazione? Decide la revisora, perché la domanda a cui sta rispondendo, capirebbe questo una lettrice esterna, è quella che il ruolo esiste per proteggere. Questo non rende inutile il parere della sviluppatrice: se il disaccordo riguarda l'accuratezza invece della formulazione, la revisora si rimette a lei, perché l'ambito è la metà che spetta all'autrice fare bene. Separare i due tipi di disaccordo, formulazione contro accuratezza, evita che la maggior parte di questi casi diventi uno stallo.

Release notes di emergenza: scrivere sotto vera pressione

Tue, 22 Sep 2026 00:00:00 GMT

La maggior parte delle release notes viene scritta dopo che il codice è pronto, revisionata con calma, e pubblicata secondo un calendario che non ha nulla a che fare con quanto urgentemente qualcuno ha bisogno di leggerla. Un rilascio d'emergenza, una patch di sicurezza, un bug di perdita dati, la correzione di un'interruzione, capovolge tutte quelle condizioni insieme: le note devono esistere prima che la maggior parte delle persone normalmente inizierebbe a scriverle, ricevono quasi nessuna revisione, e vengono lette da persone ansiose invece che rilassate. Come scrivere release notes copre il processo normale; questo riguarda cosa cambia quando non c'è più tempo per seguirlo.

Qual è l'unica cosa che una release note di emergenza deve assolutamente azzeccare?

Se chi legge deve fare qualcosa, dichiarato nella prima frase, senza alcuna cornice prima. Chi legge una release note guidata da un incidente è spesso già preoccupato, avendo sentito parlare del problema da una pagina di stato, un thread di supporto, o le proprie utenti, e una nota che apre con contesto prima dell'azione richiesta si legge come trattenere informazioni proprio nelle circostanze in cui trattenere si legge peggio. "Nessuna azione necessaria, questo corregge una vulnerabilità che non richiedeva dati utente per essere sfruttata" e "Aggiornate immediatamente: questo rilascio corregge un bug che poteva mostrare i dati di un account a un altro" sono entrambe una frase, ed entrambe fanno tutto il lavoro di cui ha bisogno chi legge nel panico prima di leggere qualsiasi altra cosa.

Il solito passaggio di editing si applica ancora quando non c'è tempo per farlo?

L'istinto di comprimere sopravvive anche quando il processo a più bozze che di solito lo produce non lo fa. La riscrittura descrive il tagliare una prima bozza prolissa fino alla sua frase essenziale; sotto pressione di tempo spesso non c'è una prima bozza da tagliare, il che significa che la disciplina deve girare nella vostra testa mentre scrivete invece che come passaggio separato dopo. Il modo più veloce per approssimarla: scrivete la frase che direste ad alta voce a qualcuno che chiede "cosa devo sapere", poi fermatevi, perché quella frase è di solito sia la più veloce da produrre sia l'unica che chi legge in quello stato processerà davvero.

Release note normale	Release note di emergenza
Scritta dopo la code review, prima della pubblicazione	Spesso scritta insieme alla correzione, prima della revisione completa
Ottimizzata per la scorribilità tra molte voci	Ottimizzata per una voce letta isolatamente, sotto stress
Può rimandare il dettaglio a un changelog collegato	Dovrebbe anteporre l'unico fatto più importante
Cornice e contesto sono benvenuti	La cornice prima dell'azione richiesta si legge come ritardo

È mai accettabile pubblicare una nota prima di essere del tutto sicuri di cosa abbia causato il problema?

Sì, se la nota è onesta su quell'incertezza invece di suggerire una certezza che non avete. "Abbiamo distribuito una correzione per tassi di errore elevati nel checkout; stiamo ancora confermando la causa radice e aggiorneremo questa nota" è difendibile e guadagna tempo correttamente; una nota che afferma una causa specifica che in realtà non avete confermato è il tipo di ipotesi che diventa ciò che la gente vi cita indietro più tardi se risulta sbagliata. La disciplina che conta qui non è la velocità di diagnosi, è non lasciare mai che la certezza della nota superi la certezza reale del team, perché un'affermazione tecnica sbagliata in una nota di emergenza fa più danno alla fiducia di un'incognita ammessa.

Troppo sicuro, non verificato:
"Corretto: una race condition nel gestore del webhook
di pagamento causava addebiti duplicati."

Onesto sotto pressione di tempo:
"Corretto: ad alcune clienti è stato addebitato due volte
un singolo ordine. Abbiamo fermato nuove occorrenze e
stiamo rimborsando gli account interessati entro 24 ore.
Stiamo indagando la causa radice."

Una nota di emergenza dovrebbe dire cosa ha causato il problema, o solo che è stato corretto?

Dite cosa è corretto e cosa dovrebbe fare chi legge; conservate la causa radice per un follow-up una volta che è davvero nota, non ipotizzata. Chi legge nel mezzo di un incidente vuole esattamente due fatti, se questo è risolto e se lo riguarda, e una spiegazione della causa radice, anche accurata, compete con quei due fatti per l'attenzione nel momento peggiore possibile per perderla. Il postmortem, pubblicato separatamente una volta finita l'indagine, è dove appartiene la causa radice; mescolare i due documenti sotto pressione di tempo produce una nota più lenta da scrivere e più lenta da leggere, l'opposto di ciò di cui ha bisogno un'emergenza.

Il problema dell'aggiornamento forzato delle app mobile si applica anche qui?

Lo stesso principio, ancora più compresso. Release notes per app mobile copre gli aggiornamenti forzati, dove la nota deve dichiarare il motivo e la scadenza prima di tutto perché chi legge è già infastidito dal non avere scelta; una release note di emergenza web è di solito opt-in per chi legge nel senso che sceglie se agire su di essa, ma lo stesso istinto "dichiarate prima il vincolo" si applica, solo per una ragione diversa: non fastidio, urgenza.

Come evitate che una nota di emergenza si legga come un'ammissione di colpa quando non dovrebbe?

Descrivete la correzione e il suo effetto, non la colpa, e resistete all'impulso di scusarvi eccessivamente, il che si legge come riempitivo per chi legge e vuole i due fatti sopra. "Abbiamo trovato e corretto un bug che riguardava alcune esportazioni" dice cosa è successo senza assegnargli dramma; "Siamo incredibilmente dispiaciuti per questo grave problema che ha colpito le nostre preziose clienti" ritarda l'informazione utile di un'intera frase per consegnare un momento emotivo che chi legge non ha chiesto. Una nota breve e fattuale non è fredda, è rispettosa dello stato reale di chi legge, che sotto vera pressione è impazienza, non bisogno di rassicurazione.

FAQ

Una release note di emergenza dovrebbe passare attraverso lo stesso processo di revisione di una normale? Uno più leggero, non nessuno: una singola revisora veloce che controlla che la nota non esageri la certezza vale i pochi minuti che costa, perché il rischio che un'affermazione tecnica non revisionata sia sbagliata è più alto proprio perché è stata scritta velocemente.

Va bene pubblicare una nota di emergenza senza alcun link a ulteriori dettagli? Solo brevemente. Una nota senza link funziona come la prima cosa pubblicata; aggiungetene uno a una pagina di stato o un follow-up appena esiste uno dei due, perché chi legge e vuole più dell'unica frase che avete dato ha bisogno di un posto dove andare, anche se quel posto dice "maggiori dettagli presto".

Una nota di emergenza dovrebbe mai essere saltata del tutto, lasciando che la correzione venga distribuita in silenzio? Solo per problemi che nessuna lettrice avrebbe potuto notare o esserne stata colpita; se c'è qualche possibilità che una lettrice abbia sperimentato il problema, la nota è ciò che le dice che è finito, e il silenzio si legge come se il problema potesse ancora essere attivo.

Per quanto tempo una nota di emergenza dovrebbe restare fissata o prominente dopo che l'incidente è risolto? Finché la finestra di ansia immediata non si chiude, tipicamente un giorno o due, poi può confluire nel changelog normale come qualsiasi altra voce; una nota che resta fissata per settimane inizia a leggersi come una preoccupazione irrisolta invece che risolta.

I breaking change di Protobuf: cosa sopravvive sul wire

Tue, 22 Sep 2026 00:00:00 GMT

Un'API REST cambia quando cambia una forma JSON, e la maggior parte di quella forma è visibile nella risposta che potete leggere in un browser. Un'API gRPC cambia quando cambia un file .proto, e il formato binario di wire di Protocol Buffers ha regole proprie su cosa può tollerare un client che non hanno nulla a che fare con quello che dicono i nomi dei campi. Due modifiche che sembrano ugualmente piccole in un diff, rinumerare un campo contro aggiungerne uno, cadono su lati opposti di una linea che breaking changes traccia in generale: una è invisibile per ogni client esistente, l'altra li rompe tutti insieme. Distinguere i breaking change di Protobuf da quelli sicuri significa leggere le regole proprie del formato di wire, non indovinare da come si legge il cambiamento in un diff .proto.

Perché la numerazione dei campi conta più del nome del campo in Protobuf?

Perché il formato di wire codifica i campi per numero, non per nome. Il codice generato in ogni linguaggio legge e scrive quei numeri; il nome del campo email nel vostro file .proto è una comodità per gli umani che non tocca mai i byte binari inviati sulla rete. Rinominare un campo, email in email_address, è sicuro sul wire binario finché il numero resta lo stesso, il che sorprende chi viene da REST, dove una chiave JSON rinominata è esattamente il tipo di cambiamento che rompe un client. L'eccezione è proprio il caso REST: i formati ProtoJSON e testo serializzano il nome, quindi una ridenominazione rompe il transcoding JSON (un grpc-gateway, per esempio), i file in formato testo e le field mask. Rinumerare quello stesso campo, tenendo il nome ma cambiando 1 in 7, è esattamente l'opposto: invisibile in una code review che mostra solo nomi, e corrompe ogni messaggio che un client invia o riceve da quel punto in poi.

Cambiamento	Sicuro sul wire	Perché
Rinominare un campo, mantenere il numero	Binario sì, JSON e testo no	La codifica binaria usa il numero; ProtoJSON e il formato testo usano il nome
Cambiare il numero di un campo	No	Ogni messaggio esistente viene ora letto come il campo sbagliato
Aggiungere un campo nuovo con numero nuovo	Sì	I client vecchi ignorano campi che non riconoscono
Rimuovere un campo, riusare il suo vecchio numero per altro	No	I dati vecchi vengono decodificati nel campo nuovo sbagliato
Cambiare il tipo di un campo in modo incompatibile (es. `int32` a `string`)	No	La codifica di wire differisce per tipo

Cosa rende diverso rimuovere un campo rispetto a farlo in una risposta JSON REST?

Il numero diventa radioattivo. Le indicazioni ufficiali di Protobuf raccomandano di marcare come reserved il numero di un campo rimosso invece di lasciarlo riusare, perché il riuso è dove avviene il danno vero: un client che esegue ancora codice generato del mese scorso invia un messaggio usando il vecchio numero del campo per il vecchio significato, e il server, che ora si aspetta che quel numero significhi qualcos'altro, interpreta male i dati in silenzio invece di rifiutarli apertamente. REST non ha una trappola equivalente, perché una chiave JSON rimossa smette semplicemente di apparire; non c'è modo che la richiesta di un client vecchio venga silenziosamente reinterpretata come qualcos'altro. Un file .proto con reserved 4, 9, 12; in cima a un messaggio è una cicatrice permanente, ed è quello il punto: impedisce che il numero venga assegnato a un campo nuovo da qualcuno che non ne conosceva la storia.

message Invoice {
  reserved 4; // era `legacy_customer_id`, rimosso il 2026-06-01
  reserved "legacy_customer_id"; // anche il nome, per JSON/testo
  string customer_id = 5;
  string status = 6;
}

Aggiungere un campo arriva mai a richiedere una voce di changelog?

Di solito non una voce di breaking change, ma spesso sì una normale, perché "sicuro sul wire" e "invisibile per chi legge e ci tiene" sono affermazioni diverse. Aggiungere un campo a un messaggio di risposta non costa nulla strutturalmente, i client vecchi decodificano il messaggio e ignorano il campo nuovo automaticamente. Ma chi costruisce una nuova integrazione contro quel servizio non ha modo di sapere che il campo esiste a meno che qualcuno non glielo dica, perché nulla in una build riuscita o in un test superato rende visibile un nuovo campo opzionale. Changelog di API copre in generale cosa deve una voce additiva a chi legge; il motivo specifico di gRPC per scriverne una comunque è che non c'è un equivalente a navigare una risposta REST in un debugger per notare che è comparsa una chiave nuova.

In cosa differisce questo da ciò con cui deve fare i conti chi chiama GraphQL?

Le regole per le aggiunte coincidono, ma l'esposizione è diversa. Deprecazione di schema GraphQL copre un modello in cui un client riceve solo i campi che richiede esplicitamente, il che rende i cambiamenti additivi essenzialmente privi di rischio e le rimozioni l'unico pericolo reale. I client gRPC, al contrario, ricevono qualunque cosa il server invii e decodificano tutto contro la propria copia compilata dello schema; l'esposizione di un client non è limitata da ciò che ha richiesto, solo da ciò che il suo codice generato sa leggere. Questa differenza conta per scrivere i changelog: una voce GraphQL può ragionevolmente assumere che i client siano protetti dai campi che non hanno richiesto, e una voce gRPC non può assumerlo affatto.

Versionare un servizio gRPC funziona come `/v1/`, `/v2/` di REST?

Il meccanismo è diverso anche quando l'intento è lo stesso. Cosa sono v1 e v2 in un'API REST copre il versionamento come percorsi URL paralleli che servono contratti diversi; i servizi gRPC tipicamente versionano tramite il nome del package nel file .proto stesso, payments.v1.InvoiceService diventa payments.v2.InvoiceService, il che cambia il nome di servizio completamente qualificato che un client chiama invece di un segmento URL che richiede. Entrambi gli approcci risolvono lo stesso problema, lasciare che un contratto vecchio continui a funzionare mentre ne esiste uno nuovo, ma un team che viene da un background REST spesso cerca un numero di versione nel posto sbagliato e si perde che la dichiarazione del package sta facendo quel lavoro.

Cosa dovrebbe nominare davvero una voce di changelog gRPC?

Il messaggio, il numero del campo, e se è additivo o una rimozione che richiede migrazione, in quell'ordine di importanza per chi legge e deve decidere se agire. "Aggiunto shipping_address (campo 8) a Order" dice a chi integra tutto il necessario per aggiornare il codice generato e iniziare a usarlo. "Riservato il campo 4 su Invoice, legacy_customer_id non c'è più" gli dice di controllare se qualcosa nella loro codebase legge ancora quel campo, cosa che una nota in stile REST "rimosso un campo dalla risposta" non comunica con la stessa urgenza, perché le rimozioni REST restituiscono semplicemente meno dati mentre il riuso dei campi Protobuf li corrompe attivamente.

FAQ

Il tipo di un campo può mai essere cambiato senza rompere il formato di wire? Solo entro specifici gruppi compatibili che Protobuf documenta, come allargare int32 a int64 in alcuni casi. Trattate qualsiasi cambio di tipo come rompente a meno che non l'abbiate controllato contro la tabella di compatibilità di Protobuf stessa; assumere compatibilità per analogia con il sistema di tipi di un linguaggio è come questo va storto.

Deprecare un campo in Protobuf funziona come la direttiva @deprecated di GraphQL? In modo simile: Protobuf supporta un'opzione di campo [deprecated = true] che gli strumenti possono mostrare. Nessuna delle due è imposta: un server GraphQL risponde comunque a una query su un campo deprecato, e un client protobuf ne codifica comunque uno. Entrambe sono consultive e hanno bisogno dello stesso supporto di changelog.

Rinumerare è mai sicuro se controllate ogni client? In un sistema completamente chiuso, in linea di principio, ma elimina l'intera proprietà di sicurezza per cui esistono i numeri di campo, e "controlliamo ogni client" è un'affermazione che smette di essere vera nel momento in cui una build viene messa in cache, un deploy viene ritardato, o viene aggiunto un client di cui nessuno si ricordava. Riservate il numero invece di riusarlo, anche internamente.

I servizi gRPC hanno bisogno di una pagina di changelog come un'API REST pubblica? Solo se team esterni li consumano senza leggere direttamente i diff .proto, lo stesso test "chi c'è dall'altra parte" che changelog di API interne applica in generale. Un servizio gRPC consumato solo da altri servizi dello stesso team può spesso saltare un changelog formale a favore della cronologia dei commit, perché chiunque lo legga ha già lo schema aperto.

Formati file del changelog: JSON, YAML o solo Markdown

Thu, 17 Sep 2026 00:00:00 GMT

La maggior parte dei team inizia un changelog come file Markdown perché è la via di minor resistenza: leggibile nel diff di una pull request, leggibile su GitHub senza renderizzare nulla, e familiare a chiunque abbia mai scritto un README. Questa scelta funziona bene finché qualcosa di diverso da una persona non deve leggere il file, una pagina, un widget, un riepilogo via email, e allora il formato smette di essere gratuito. Automazione del changelog copre il requisito strutturale in generale, un tipo, una data, un corpo e un link; qui si tratta di quale formato file consegna davvero quella struttura e cosa costa arrivarci con ciascuno.

Cosa c'è di sbagliato in un changelog Markdown semplice?

Niente, finché qualcosa non deve riparsarlo in campi. Un titolo, una data e un elenco puntato sotto sono banali da leggere per una persona e genuinamente difficili da parsare in modo affidabile, perché Markdown non ha uno schema: la data potrebbe stare nel titolo, in grassetto sulla prima riga, o mancare del tutto in una voce vecchia, e ognuna di queste varianti è Markdown valido che una persona legge correttamente e un parser no. I team che automatizzano un changelog Markdown finiscono di solito per scrivere un parser artigianale basato su regex che si rompe alla prima volta che la formattazione di una voce devia anche leggermente, il che succede spesso, perché niente impone coerenza al momento della scrittura.

Cosa vi dà davvero un formato strutturato?

Una garanzia che ogni voce abbia la stessa forma, verificata quando la voce viene scritta invece di indovinata quando viene letta. Un file JSON o YAML con uno schema definito, tipo, data, versione, pubblico, corpo, link, fallisce rumorosamente se manca un campo obbligatorio, esattamente come farebbe una risposta API rigida; un file Markdown renderizza semplicemente ciò che c'è, corretto o no. Questa differenza è invisibile fino al giorno in cui uno script ha bisogno della data di ogni voce per ordinare un feed, e metà delle voci ce l'ha in un posto diverso.

# CHANGELOG.yml
- date: 2026-09-05
  type: breaking
  version: v2
  audience: api
  body: "POST /invoices now rejects a currency mismatch instead of silently converting."
  link: /blog/api-changelog/

Questo significa che il file leggibile dall'uomo deve sparire?

No, e cercare di far fare a un file YAML o JSON anche da cosa una persona legge in una pull request è di solito un errore nella direzione opposta: revisionare un diff di JSON annidato è peggio che revisionare una frase in prosa, e una revisora che deve parsare mentalmente una struttura dati per cogliere un errore di formulazione è una revisora che prima o poi smetterà di coglierli. I due formati possono coesistere: i dati strutturati sono la fonte di verità che legge una pipeline di automazione, e un rendering generato in Markdown o HTML è ciò che una persona effettivamente revisiona e legge, prodotto dal file strutturato invece di essere mantenuto a mano in parallelo.

Formato	Leggibile dall'uomo così com'è	Parsabile da macchina senza codice su misura	Fallimento comune
Markdown	Sì	No	Forma incoerente delle voci rompe i parser ingenui
JSON	Scarso	Sì	Prolisso; facile da modificare a mano in JSON non valido
YAML	Discreto	Sì	Sensibile agli spazi; un'indentazione sbagliata è un errore di parsing silenzioso, non rumoroso

Quale formato strutturato è davvero più facile da modificare a mano, JSON o YAML?

YAML, per chi scrive voci a mano invece che tramite un generatore, perché elimina il quoting e l'abbinamento di parentesi che JSON richiede per ogni stringa e oggetto annidato. Il compromesso è che la sensibilità di YAML agli spazi fallisce silenziosamente in un modo in cui i disallineamenti di parentesi di JSON di solito non lo fanno: un parser JSON rifiuta subito un input malformato, mentre un parser YAML può accettare un file mal indentato e semplicemente parsarlo nella struttura sbagliata, il che è un fallimento peggiore perché niente vi dice che è successo. Se le voci sono sempre e solo scritte da uno script, questo compromesso praticamente scompare e il parsing più rigido di JSON diventa la scelta predefinita più sicura.

Una pagina di changelog ha bisogno di un proprio formato strutturato, separato dal file che la alimenta?

Non uno separato, lo stesso renderizzato diversamente. Una pagina di changelog copre come rendere la pagina stessa leggibile da macchina tramite un feed JSON e markup schema.org; quel feed è output generato, non una seconda fonte di verità da mantenere sincronizzata con il file sottostante. Mantenere dati strutturati a mano in due posti, un file sorgente e il feed di una pagina, è come i due finiscono per divergere, quindi la decisione sul formato file presa qui dovrebbe essere l'unica cosa da cui tutto ciò che segue, pagina, widget, email, viene generato, mai copiato a mano.

Vale il costo di migrazione convertire un changelog Markdown esistente in un formato strutturato?

Di solito solo una volta che l'automazione è l'obiettivo reale, non prima. Un progetto di una sola persona che pubblica un file Markdown in un README di GitHub non ha un vero bisogno di automazione, e convertirlo in YAML non compra nulla se non cerimonia. La conversione si ripaga da sola nel momento in cui più di un consumatore a valle, una pagina, un'email di riepilogo, un feed pubblico, ha bisogno di leggere gli stessi dati, perché è esattamente il punto in cui le incoerenze di un parser Markdown iniziano a produrre output visibilmente sbagliato invece di essere solo fastidiose da mantenere.

FAQ

Un changelog Markdown può essere reso parsabile senza cambiare formato del tutto? Parzialmente, con il frontmatter: un piccolo blocco YAML in cima a ogni voce (data, tipo, versione) accanto a un corpo Markdown per la prosa. Questo ottiene i campi strutturati di cui un parser ha bisogno senza forzare l'intera voce in JSON o YAML, ed è un ragionevole punto intermedio per un team non ancora pronto per una migrazione completa.

Il formato del file conta per la SEO o per come si posiziona una pagina di changelog? Non direttamente. I motori di ricerca leggono la pagina renderizzata, non il file sorgente, quindi il formato del file è invisibile per loro; ciò che conta per la pagina stessa è se è leggibile da macchina di per sé, il che è una questione separata da cosa la genera.

Ogni voce di changelog dovrebbe passare attraverso lo stesso file, o i tipi possono essere divisi su più file? Un file solo è più semplice finché il volume delle voci non lo rende scomodo da diffare o revisionare; dividere per anno o per categoria è una valvola di sfogo ragionevole una volta che i diff di un singolo file diventano troppo grandi da revisionare sensatamente, ma aggiunge un passaggio di merge prima che qualcosa a valle possa leggere "tutte le voci" come un'unica lista.

Esiste un formato file standard per il changelog, come esiste uno standard per RSS? Non uno ampiamente adottato. Keep a Changelog propone una convenzione Markdown, e diversi strumenti ne hanno una propria; un changeset è un file Markdown con un frontmatter YAML che nomina il pacchetto e il bump, cioè lo schema a frontmatter descritto sopra. Nessuno di questi è un formato che altri strumenti leggono di serie come i lettori RSS capiscono RSS universalmente.

Richieste duplicate: unire senza perdere la voce originale

Thu, 17 Sep 2026 00:00:00 GMT

Tre clienti chiedono la stessa capacità in tre settimane diverse, formulata in tre modi diversi, e un processo di triage costruito per intercettare i duplicati fa il suo lavoro: li raggruppa, li conta come un'unica richiesta con tre voti, e il backlog resta pulito. Questa è la parte facile. Quali etichette valgono la pena copre il raggruppare per capacità sottostante prima di smistare per formulazione come soluzione meccanica ai duplicati; quello che non copre è cosa succede alle parole stesse quando tre richieste diventano una sola riga, e quella perdita è di solito più grande del problema di conteggio dei duplicati che ha risolto.

Cosa si perde davvero quando i duplicati vengono uniti?

La formulazione specifica usata da ogni richiedente, che spesso è più informativa del conteggio voti in cui collassa. Una cliente potrebbe chiedere "un modo per esportare i risultati filtrati", un'altra "esportazione CSV che rispetti i miei filtri salvati", e una terza "esportazione che non includa colonne nascoste". Tutte e tre sono la stessa richiesta sottostante, raggruppata correttamente, ma ogni formulazione porta un'enfasi leggermente diversa su cosa conta per quella persona, e una fusione che conserva solo la formulazione della prima segnalazione butta via completamente le altre due. Il conteggio sopravvive; la trama che aiuterebbe qualcuno a costruire la versione giusta della funzionalità, no.

Perché la trama conta se il conteggio voti già dice che esiste domanda?

Perché domanda e design sono domande diverse, e solo la formulazione specifica risponde alla seconda. Dieci voti su "esportazione" dice a un team che vale la pena costruire la funzionalità; non dice nulla su se "esportazione" significhi CSV, PDF, un'email programmata o un endpoint API, e una fusione che scarta nove delle dieci segnalazioni originali a favore della formulazione della prima può silenziosamente restringere la specifica a qualunque cosa la prima richiedente abbia chiesto per caso, anche se le altre nove volevano qualcosa di sottilmente diverso. Cosa dovrebbe registrare davvero una richiesta di funzionalità copre proprio questo divario dal lato dell'acquisizione; unire i duplicati è dove riemerge dopo l'acquisizione, proprio nel punto in cui un team ha più bisogno della gamma di ciò che è stato davvero chiesto.

Com'è un processo di fusione che conserva la formulazione invece di scartarla?

Aggiungere invece di sostituire. L'elemento canonico conserva un unico titolo per la vista del backlog, ma la formulazione originale di ogni segnalazione unita resta attaccata ad esso, o come elenco di citazioni o come ticket sorgente collegati, così chiunque riveda l'elemento in seguito può vedere la gamma reale di ciò che le persone hanno chiesto invece del riassunto di una persona del team. Costa quasi niente costruirlo, un campo sul ticket invece di un nuovo sistema, ed è la differenza tra una fusione che comprime informazione e una che comprime solo come viene mostrata.

Funzionalità: Esportazione CSV filtrata
Voti: 12
Richieste unite:
  - "un modo per esportare i risultati filtrati" (acct_4421)
  - "esportazione CSV che rispetti i miei filtri salvati" (acct_8832)
  - "esportazione che non includa colonne nascoste" (acct_1097)
  ...

Ogni duplicato merita di essere unito, o ci sono corrispondenze false?

Alcune sono corrispondenze false, e trattare "suona simile" come "è la stessa richiesta" è un modo di fallire a sé stante. "Lasciami esportare i miei dati" e "lasciami esportare solo la vista filtrata" possono essere raggruppate da una corrispondenza di parola chiave su "esportare" mentre in realtà descrivono due ambiti diversi della stessa capacità generale; unirle o gonfia il conteggio voti per la cosa sbagliata o, peggio, rilascia la versione più ristretta perché è arrivata prima per caso. Un passaggio umano sul raggruppamento, anche veloce, coglie questo prima che si accumuli; una corrispondenza automatica per similarità da sola unirà troppo per vocabolario e troppo poco per intento.

Quando dovrebbe girare davvero il controllo dei duplicati, all'intake o dopo?

Entrambi, per motivi diversi. Controllare all'intake coglie il caso ovvio, una nuova richiesta che riformula qualcosa già aperto, prima ancora che diventi una voce non tracciata a sé stante; una ricerca per similarità contro le richieste aperte al momento dell'invio gestisce la maggior parte di questi casi senza alcun intervento umano. Un secondo passaggio più avanti, con un ritmo più lento, coglie il caso che l'intake si perde: due richieste che hanno usato un linguaggio abbastanza diverso da sfuggire a una corrispondenza per parola chiave o per embedding al momento, ma che si scoprono, una volta che un team ne ha viste una dozzina di varianti, descrivere la stessa capacità di fondo. Saltare il secondo passaggio lascia i quasi-duplicati sparsi sotto titoli separati a tempo indeterminato, ciascuno con il proprio piccolo conteggio voti che non si somma mai al numero che l'avrebbe fatta costruire.

La richiedente dovrebbe sapere che la sua segnalazione è stata unita a un elemento esistente?

Sì, ed è la stessa disciplina di chiudere il ciclo di feedback del cliente applicata un passo prima del solito: una richiedente che ha inviato qualcosa e non ne sente più parlare conclude che la sua richiesta non è andata da nessuna parte, anche se è stata unita correttamente a un elemento con altri undici voti che alla fine è stato rilasciato. Un breve riconoscimento, "abbiamo combinato questo con una richiesta esistente che anche altri hanno fatto", costa un messaggio ed evita che una cliente reinvii la stessa richiesta ogni pochi mesi perché non ha visibilità su se sia mai stata effettivamente tracciata.

Unire cambia a chi viene dato credito quando la funzionalità viene rilasciata?

Dovrebbe includere tutti, non solo chi ha inviato per primo. Chiudere il ciclo di feedback copre l'avvisare le richiedenti quando la loro richiesta viene rilasciata; per un elemento unito questo significa ogni account collegato alla fusione, non solo quello la cui formulazione è diventata il titolo canonico, perché dal punto di vista di ogni richiedente lei ha chiesto questo ed è stato rilasciato, indipendentemente da quale formulazione un processo di triage abbia scelto di conservare. Con Changeloop significa che la pull request nomina ogni issue collegato (Fixes #142, fixes #187); un issue che non nomina non riceve alcun commento.

FAQ

Quanta formulazione vale la pena conservare per richiesta unita, una citazione o un link completo al ticket? Una citazione breve di solito basta per il caso comune, dato che il suo scopo è far vedere a chi revisiona la gamma di formulazioni a colpo d'occhio; conservate anche il link completo al ticket quando l'originale aveva contesto extra significativo, come uno screenshot o una descrizione dettagliata del flusso che una citazione di una riga appiattirebbe.

Conservare la formulazione di ogni duplicato rende il backlog più difficile da scorrere? No, se è collassata di default. Il titolo canonico è ciò che vede chi scorre velocemente; la formulazione unita è a un clic o un'espansione di distanza, presente per chi fa ricerca più approfondita ma senza affollare la vista di chi conta solo i voti.

Cosa succede se due richieste sembrano identiche ma si scoprono volere cose diverse una volta costruite? Separatele di nuovo nel momento in cui diventa chiaro, e trattate la fusione originale come una decisione ragionevole presa con le informazioni disponibili all'epoca, non come un errore da evitare di ripetere. Un sistema di raggruppamento che non separa mai nulla finirà per avere alcune fusioni sbagliate incorporate permanentemente.

C'è una soglia di voti oltre la quale una richiesta unita dovrebbe ricevere una revisione umana della formulazione sottostante? Non un numero fisso, ma qualsiasi richiesta vicina a una decisione di costruzione la merita indipendentemente dal conteggio voti, perché è il punto in cui la differenza tra "esportazione" e "esportazione come CSV con filtri salvati" smette di essere una sfumatura e comincia a essere la specifica.

Deprecazione di GraphQL senza numero di versione

Thu, 17 Sep 2026 00:00:00 GMT

Un'API REST può pubblicare /v2/ accanto a /v1/ e lasciare che chi chiama si muova al proprio ritmo. GraphQL ha uno schema a un endpoint, e ogni client, l'app mobile con la build dell'anno scorso e la dashboard interna distribuita stamattina, interroga lo stesso grafo. Non c'è URL da biforcare. Deprecare un campo significa marcarlo come deprecato sul posto, in uno schema da cui tutti già dipendono, il che rende la disciplina diversa da REST anche se il problema di fondo, dire a chi chiama che qualcosa sta per sparire, è lo stesso che deprecazione di API copre in generale.

Come marca GraphQL un campo come deprecato, se non c'è versione da incrementare?

Con la direttiva @deprecated, applicata direttamente al campo:

type Product {
  price: Float @deprecated(reason: "Use priceV2 for multi-currency support.")
  priceV2: Money
}

Il campo resta interrogabile. Non sparisce, non restituisce un 404, non cambia comportamento; porta solo una nota leggibile da macchina che la maggior parte degli strumenti GraphQL, GraphiQL, Apollo Studio, i linter di schema, mostrerà a chiunque navighi lo schema o scriva una query contro di esso. Questo è l'intero meccanismo. Non c'è un endpoint di deprecazione separato, nessun header, nessun documento aggiuntivo richiesto dalla specifica, il che è sia l'attrattiva sia la trappola: la direttiva è facile da aggiungere e facile da ignorare, perché niente costringe un client a guardarla.

Qualcuno vede davvero il motivo della deprecazione?

Solo chi usa lo schema direttamente, tramite introspezione o un editor consapevole dello schema, e questo è un pubblico più piccolo dei lettori abituali di un changelog di API. Un'app mobile costruita contro una query sei mesi fa ha già quella query incorporata nel suo binario; continuerà a chiedere price e continuerà a ricevere una risposta, deprecato o no, finché qualcuno non ricostruisce l'app con il nuovo campo e rilascia un aggiornamento. La direttiva dice a chi scrive codice nuovo di non usare il campo vecchio. Non fa nulla per il client già distribuito e in esecuzione.

Meccanismo	Chi raggiunge
Direttiva `@deprecated`	Sviluppatrici che navigano lo schema o scrivono nuove query
Fallimenti CI del linter di schema	Il team proprietario del codice client, se ne gestisce uno
Una voce di changelog	Chiunque la legga, incluso un team client senza linter
Niente (il campo funziona e basta)	Un client già costruito che usa il campo vecchio

Un campo deprecato dovrebbe comunque avere una voce di changelog?

Sì, e fa più lavoro della sola direttiva, perché un changelog raggiunge persone che la direttiva non può: un team partner che consuma il grafo senza navigarne lo schema, un client costruito contro una copia cachata dello schema di mesi fa, chiunque se ne accorgerebbe solo leggendo prosa. Changelog di API copre in generale cosa deve una voce a chi chiama; una voce GraphQL deve una cosa che REST raramente deve esplicitare, perché chi chiama REST la deduce dal numero di versione: se il campo vecchio funziona ancora oggi, funziona ancora con un avviso, o ha effettivamente smesso di restituire dati. La direttiva da sola non risponde a nulla di questo per una lettrice che non ha mai aperto lo schema.

Quando è davvero sicuro rimuovere un campo dallo schema?

Solo quando i log delle query mostrano che nessuno lo chiede più, il che è una domanda di utilizzo, non di calendario. Un campo può portare @deprecated per un anno ed essere ancora portante per un client mai ricostruito; rimuoverlo su un calendario fisso, come spesso fa un Sunset REST, rompe quel client senza alcun avviso su cui possa agire, perché GraphQL non gli dà nulla su cui agire oltre alla direttiva che non ha mai letto. Registrate l'utilizzo a livello di campo prima di impegnarvi su una data di rimozione, e trattate qualsiasi conteggio di query diverso da zero come una pausa, non un conto alla rovescia.

Aggiungere un campo comporta lo stesso rischio che in un'API REST?

Meno, per un nuovo campo, perché un client GraphQL riceve solo i campi che chiede esplicitamente. Aggiungere priceV2 accanto a price non può rompere una query esistente nel modo in cui aggiungere un campo a una risposta JSON REST può rompere un deserializzatore rigido, dato che niente costringe il client a richiedere il campo nuovo. Aggiungere un valore a un enum esistente è l'eccezione che vale la pena nominare nello stesso respiro: un client che fa uno switch esaustivo su ogni valore dell'enum, cosa che i linguaggi fortemente tipizzati incoraggiano, si rompe nel momento in cui arriva un valore nuovo, indipendentemente dal fatto che una query lo chiedesse. La sicurezza vale solo per i campi e i membri di union su cui un client sceglie di entrare; non vale per un insieme chiuso che il codice di un client enumera a mano.

Cosa serve a una voce di changelog GraphQL che non serve a una REST?

La forma della query, non solo il nome del campo, perché "il campo price è deprecato" manca del pezzo di cui chi chiama ha davvero bisogno: quali tipi e quali query lo toccano. Una voce utile nomina il tipo, il campo, il campo sostitutivo e, se potete generarlo, le query reali in produzione che ancora richiedono la forma vecchia. Quest'ultimo pezzo, legare l'avviso di deprecazione all'utilizzo reale, è ciò che chi chiama REST ottiene gratis dai log del server su un URL e chi chiama GraphQL no, perché ogni query colpisce lo stesso endpoint indipendentemente da cosa chiede.

Qualcos'altro oltre a un campo può portare la direttiva `@deprecated`?

I valori enum, usando la stessa direttiva sulla definizione del valore stesso invece che su quella del campo:

enum ShippingMethod {
  STANDARD
  EXPRESS
  OVERNIGHT @deprecated(reason: "Use EXPRESS with priority: true instead.")
}

La specifica definisce @deprecated per esattamente due posizioni, la definizione di un campo o un valore enum, e nient'altro nella release stabile; la deprecazione a livello di argomento e di campo di input esiste solo nel linguaggio delle bozze successive, non in quello che la maggior parte dei server implementa oggi. Un valore enum marcato in questo modo resta un valore legale che un server può ancora restituire o accettare, la stessa promessa di non-rottura che fa un campo deprecato, ed è quello che lo rende sicuro da pubblicare prima di rimuovere davvero il valore.

FAQ

GraphQL supporta qualcosa come un header Sunset per un intero endpoint? No, perché di solito c'è un solo endpoint. Il tempismo della deprecazione vive a livello di campo, nel testo del motivo della direttiva @deprecated e in qualunque changelog o guida alla migrazione un team pubblichi accanto ad esso, non in un header di risposta che un client possa leggere programmaticamente.

Un campo deprecato può essere rimosso e riaggiunto in seguito con un tipo diverso? Solo come nuovo nome di campo. Reintrodurre lo stesso nome di campo con un tipo cambiato è esattamente il breaking change che il ciclo di deprecazione esiste per evitare; date al sostituto un proprio nome, come fa priceV2, e lasciate che il vecchio si estingua completamente prima che il nome sia libero per il riutilizzo.

Il testo del motivo @deprecated dovrebbe linkare alla voce di changelog? Sì, quando gli strumenti dello schema lo supportano. Il campo motivo accetta una stringa semplice, e un URL dentro quella stringa è il percorso più breve da una sviluppatrice che fissa l'output dell'introspezione alla spiegazione più completa che una voce di changelog può dare.

Un cambiamento di schema GraphQL è mai retrocompatibile in un modo in cui REST non lo è? I cambiamenti additivi di campo, sì, per il motivo sopra: i client ottengono solo ciò che chiedono. I nuovi valori enum sono l'eccezione, perché un client che enumera un insieme chiuso può rompersi su un valore che non si aspettava. Le rimozioni e i cambiamenti di tipo sono esattamente rompenti quanto i loro equivalenti REST.

Come scrivere una guida di migrazione per API

Mon, 07 Sep 2026 00:00:00 GMT

Una guida di migrazione API è il documento che trasforma un cambiamento incompatibile in una checklist invece che in un'interruzione: cosa è cambiato, cosa fare al riguardo, ed entro quando. Una voce di changelog può nominare un cambiamento incompatibile in due frasi; una guida di migrazione è ciò che chi chiama apre davvero quando quelle due frasi dicono "questo ti rompe" e ha bisogno di sapere esattamente cosa modificare. Pubblicare la voce senza la guida è come chi chiama scopre un cambiamento incompatibile da un ticket di supporto invece che dal documento scritto per prevenirlo.

Cos'è una guida di migrazione API?

Un documento passo passo che porta chi chiama dalla vecchia forma di un'API alla nuova, scritto per chi ha codice da modificare, non per chi sta decidendo se adottare l'API. Questa distinzione conta: una guida di migrazione presuppone un'integrazione esistente e traffico di produzione esistente, quindi deve coprire il rollback, la migrazione parziale, e come capire se la migrazione è riuscita, nulla di ciò che serve a una guida per una prima integrazione.

Documento	Presuppone	Risponde a
Guida di migrazione	Un'integrazione esistente	Come passo dalla vecchia forma alla nuova?
Voce di changelog	Niente, solo che la lettrice controlla	Cosa è cambiato, e quando?
Riferimento API	Niente, o una prima integrazione	Cosa fa questo endpoint?
Avviso di deprecazione	Un'integrazione che usa il vecchio	Quando smette di funzionare?

Una guida di migrazione si colloca di solito tra gli ultimi due: un avviso di deprecazione fa partire un conto alla rovescia, e la guida di migrazione è ciò che chi chiama segue prima che quel conto scada.

Quando un cambiamento ha bisogno di una guida di migrazione, e non solo di una voce di changelog?

Quando c'è più di un passaggio tra il vecchio comportamento e il nuovo, o quando il cambiamento tocca abbastanza punti di chiamata che chi chiama trae beneficio da un esempio lavorato più che da una descrizione. Cos'è un cambiamento incompatibile, e come rilasciarlo copre il test per stabilire se un cambiamento è incompatibile; se la risposta è sì, la seconda domanda è se la correzione è una modifica di una riga o una vera migrazione. Un campo rinominato può gestirlo chi chiama solo con la voce di changelog. Un cambiamento all'autenticazione, alla paginazione o alla gestione degli errori si guadagna quasi sempre una guida, perché il codice di sostituzione corretto non è ovvio da una descrizione di una frase.

Cosa deve contenere una guida di migrazione?

Cinque cose, e saltarne anche una sola è ciò che trasforma una guida in una pagina che chi chiama legge una volta e poi abbandona per procedere per tentativi. Il codice vecchio, mostrato così come apparirebbe davvero in un progetto. Il codice nuovo, mostrato allo stesso modo, non come descrizione astratta della differenza. Cosa si rompe se non si cambia nulla, detto chiaramente, perché "nulla" è una risposta valida e comune che chi chiama deve comunque sentirsi dire esplicitamente. Un modo per verificare che la migrazione abbia funzionato, come un campo di risposta o un codice di stato da controllare. E una tempistica: quando il vecchio comportamento smette di funzionare, e se entrambe le forme sono disponibili nel frattempo.

## Migrazione dei campi valuta da float a intero (v3.0.0)

Prima:
  { "amount": 19.99 }

Dopo:
  { "amount": 1999 }  // unità di valuta più piccola (centesimi)

Cosa cambia: `amount` è ora un intero nell'unità più piccola della
valuta dell'account. Il codice che legge `amount` come float leggerà
un valore 100 volte troppo grande a partire dal 1 ottobre 2026.

Verifica: dopo la migrazione, un addebito di 19,99 dovrebbe leggersi
come `amount: 1999`, non come `amount: 19.99`.

Tempistica: v2 continua a restituire float fino al 15 gennaio 2027.
v3 restituisce interi dal lancio. Entrambe le versioni sono attive ora.

Ognuna di queste cinque cose risponde a una domanda che chi chiama dovrebbe altrimenti indovinare o chiedere al supporto, ed è proprio quello il costo reale che una guida di migrazione fa risparmiare.

Chi dovrebbe scriverla, e quando?

Chi ha progettato il cambiamento, nello stesso momento in cui viene rilasciato, non un team di supporto che la ricostruisce dai ticket in seguito. Chi ha preso la decisione sa su quali parti del vecchio comportamento nessuno avrebbe dovuto fare affidamento e quali erano un contratto accidentale; una guida scritta più tardi da qualcuno senza quel contesto tende o a spiegare troppo l'ovvio o a perdere l'unico caso limite che rompe davvero le persone. La guida e la voce di changelog che annuncia il cambiamento incompatibile dovrebbero uscire insieme, con la voce che rimanda alla guida invece di ripeterla.

Come si collega questo al versionamento e al changelog API?

Direttamente: una guida di migrazione è la versione dettagliata di ciò che una voce MAJOR in semantic versioning e il tuo changelog riassume solo in una frase. La voce di changelog dice che un cambiamento è incompatibile e a grandi linee cosa è cambiato; la guida di migrazione è il link che quella voce dovrebbe portare. Changelog di API: cosa pubblicare e chi lo legge elenca la guida di migrazione come uno dei cinque documenti che un'API mantiene, ognuno risponde a una domanda diversa; questa è quella che risponde "come passo davvero da A a B", e si guadagna una pagina tutta sua proprio perché quella risposta di solito è troppo lunga per una voce di changelog.

Per quanto tempo dovrebbe restare pubblicata una guida di migrazione?

Almeno finché il vecchio comportamento resta raggiungibile, e idealmente anche dopo. Chi migra con diciotto mesi di ritardo, dopo aver ignorato tre avvisi di deprecazione, ha comunque bisogno della guida, e cancellarla il giorno in cui il vecchio comportamento viene spento garantisce solo che chi ne ha più bisogno non la trovi. Tienila a un URL stabile e aggiorna la sezione tempistica invece di ritirare la pagina. La guida di upgrade di Stripe è un esempio pubblico di questo schema: una pagina sola, mantenuta aggiornata release dopo release, invece di un documento nuovo per ogni versione che diventa vecchio nel momento in cui esce la successiva. La vostra guida merita un posto altrettanto trovabile, accanto alla documentazione che chi chiama sta già leggendo, invece che sepolta in un archivio del blog.

FAQ

Ogni cambiamento incompatibile ha bisogno di una guida di migrazione? No. Un cambiamento che chi chiama può risolvere solo con la voce di changelog, come un singolo campo rinominato con un sostituto ovvio, non ha bisogno di una guida separata. Un cambiamento che tocca più punti di chiamata o richiede un esempio lavorato, sì.

Una guida di migrazione dovrebbe stare con la documentazione API o nel changelog? Con la documentazione, collegata dalla voce di changelog. La voce è ciò che una lettrice vede per prima; la guida è ciò di cui ha bisogno una volta deciso di agire, e appartiene accanto al materiale di riferimento che chi chiama sta già usando.

Qual è la differenza tra una guida di migrazione e un avviso di deprecazione? Un avviso di deprecazione dichiara che qualcosa sta per sparire ed entro quando. Una guida di migrazione sono le istruzioni su cosa fare al riguardo. Un avviso di deprecazione senza guida di migrazione collegata dice a chi chiama una scadenza senza dirle come rispettarla.

Il vecchio e il nuovo comportamento andrebbero entrambi documentati durante una finestra di migrazione? Sì, sulla stessa pagina se possibile, così chi chiama vede esattamente cosa è cambiato invece di ricostruirlo da due documenti separati scritti in momenti diversi.

Un check di changelog per GitHub Actions

Mon, 07 Sep 2026 00:00:00 GMT

Ogni team che mantiene un changelog a mano ha avuto la stessa conversazione dopo lo stesso incidente: un rilascio è uscito senza voce, qualcuno chiede perché, e la risposta onesta è che la persona che l'avrebbe scritta stava andando veloce e il passaggio del changelog viveva solo nella memoria. Automazione del changelog copre cosa una pipeline può automatizzare in sicurezza e cosa ha ancora bisogno di una persona; un check di changelog in CI è l'altra metà di questo problema, perché automatizzare la scrittura non aiuta se nessuno è obbligato a innescarla in primo luogo. GitHub Actions è dove la maggior parte dei team esegue già i controlli delle proprie pull request, quindi è lì che vive anche questo.

Perché "chiediamo alle persone di aggiungere una voce" fallisce con un modello prevedibile?

Perché compete per l'attenzione con tutto il resto in una pull request, ed è l'unica parte senza conseguenza immediata nel saltarla. I test falliscono rumorosamente e bloccano il merge. Una voce di changelog mancante non blocca niente, quindi perde nel momento in cui qualcuno ha fretta, che nella pratica è la maggior parte delle volte. Una politica imposta dalla memoria si degrada esattamente al ritmo che ci si aspetterebbe: bene per le prime settimane dopo che tutti sono d'accordo, poi silenziosamente abbandonata appena la persona a cui importava va in vacanza o cambia team.

Cosa verifica davvero un check CI per una voce di changelog?

Non la qualità della scrittura, solo che una voce esista e sia ben formata, che è l'ambito giusto per un check di changelog che gira in CI invece che nella testa di una persona. Una forma comune: il check guarda il diff della PR e richiede o un nuovo file in una directory di changeset (il modello che Changesets e strumenti simili usano) o una riga modificata in un file di changelog, e fa fallire la build se nessuno dei due esiste. La revisione di cosa dice davvero la voce accade ancora dove è sempre accaduta, nel code review, perché quel giudizio non appartiene a uno script.

Cosa verifica il check CI	Cosa non verifica
Esiste un changeset o una riga di changelog nel diff	Se la formulazione è chiara
La voce fa riferimento al pacchetto giusto, in un monorepo	Se il cambiamento merita davvero una voce
Il file è sintatticamente valido (front matter, forma JSON)	Se la voce è onesta sull'impatto

Ogni PR ne ha bisogno, o alcuni cambiamenti sono esenti?

Alcuni sono esenti, e la lista delle eccezioni è dove questi sistemi vengono davvero costruiti o abbandonati. Un aggiornamento di dipendenza senza effetto visibile, un cambiamento solo di test, un refactor interno senza cambiamento di comportamento: nessuno di questi dovrebbe costringere chi contribuisce a inventare una voce di changelog per qualcosa a cui nessuno che legge il changelog tiene. Il modello che funziona è un'etichetta o un flag che chi contribuisce può applicare (no-changelog-needed) e che soddisfa il check CI senza file, revisionato da chi approva la PR, così l'eccezione stessa passa lo stesso controllo che passerebbe una voce.

Cosa succede alle eccezioni legittime, come un hotfix urgente?

Il gate appartiene al merge, non al deploy: un hotfix sotto vera pressione di tempo può fare merge con una voce segnaposto o un ticket di follow-up, purché il check CI sia soddisfatto dall'intenzione invece che solo da un paragrafo finito; alcuni team accettano uno stub di una riga che una maintainer rifinisce prima del prossimo taglio di rilascio. Ciò che il gate non dovrebbe mai permettere è saltare il passaggio in silenzio, perché uno stub che viene dimenticato è un fallimento minore di una voce mai esistita, e uno stub lascia almeno una traccia che qualcuno può trovare dopo.

# .github/workflows/changelog-check.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
  changelog:
    if: >-
      !contains(github.event.pull_request.labels.*.name,
      'no-changelog-needed')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # the diff needs the base branch
      - name: Require changelog entry
        run: |
          base="origin/${{ github.base_ref }}"
          if ! git diff --name-only "$base"...HEAD \
              | grep -q '^\.changeset/'; then
            echo "No changeset. Add one, or have a maintainer"
            echo "apply the no-changelog-needed label."
            exit 1
          fi

Come si fa a sapere che il check stesso è corretto prima che inizi a bloccare PR reali?

Aprite prima una pull request di prova su un branch usa-e-getta: una con un changeset, una senza, e una con l'etichetta di eccezione, e confermate che tutte e tre ottengono l'esito atteso prima che il check si applichi al lavoro di qualcun altro. Un check di changelog che fallisce aperto, facendo passare ogni PR perché una condizione è stata scritta al contrario, è peggio che non avere nessun check, perché sembra una copertura che non esiste davvero. workflow_dispatch sullo stesso file, eseguito manualmente contro un paio di PR recenti già mergiate, cattura la maggior parte di questi errori senza bisogno di una pull request live.

La stessa idea funziona anche fuori da GitHub Actions?

La forma si porta dietro, cambia solo la sintassi. GitLab CI esprime la stessa regola come un blocco rules di un job che controlla $CI_MERGE_REQUEST_LABELS invece di un if di GitHub Actions, e un'approvazione obbligatoria della merge request può sostituire il passaggio di revisione dell'eccezione. Il check descritto in questo articolo è su GitHub Actions perché è la piattaforma su cui già si trova la maggior parte di chi lo legge, ma il requisito di fondo, un gate verificato da una macchina invece di una convenzione chiesta a voce, è lo stesso ovunque giri una CI prima di un merge.

Funziona allo stesso modo in un monorepo?

Serve un pezzo in più: per quale pacchetto è la voce. Changelog di monorepo copre perché un singolo file per l'intero repo smette di funzionare appena i pacchetti vengono rilasciati indipendentemente; il check CI eredita lo stesso requisito; un changeset che non nomina un pacchetto non è una prova utile che il changelog giusto si aggiornerà, solo che qualche file è cambiato da qualche parte nel diff. Gli strumenti costruiti per questo (Changesets è quello comune nell'ecosistema JavaScript) chiedono a chi contribuisce di scegliere il pacchetto interessato e un bump semver nello stesso momento in cui il changeset viene creato, così il check CI ottiene entrambi i pezzi gratis invece di inferirli dopo.

FAQ

Il check CI dovrebbe bloccare il merge, o solo avvisare? Bloccare. Un avviso è funzionalmente identico a chiedere gentilmente, che è proprio la cosa già fallita. L'etichetta di eccezione esiste proprio perché un caso genuino di solo-avviso abbia comunque un percorso legittimo attraverso lo stesso gate rigido.

Chi revisiona se un'etichetta di eccezione è stata applicata correttamente? Chi approva la pull request, come parte della revisione che sta già facendo comunque. L'etichetta non dovrebbe mai essere auto-applicata e non revisionata, o diventa la stessa scappatoia silenziosa che il gate doveva chiudere.

Imporlo in CI sostituisce il bisogno di una pipeline di automazione del changelog? No, la alimenta. Automazione del changelog copre come trasformare voci strutturate in una pagina, un feed e un'email; il check CI è ciò che garantisce che quelle voci strutturate esistano per automatizzarle in primo luogo.

Qual è la versione più piccola di questo che vale la pena costruire per prima? Un singolo check che fallisce se nessun file è cambiato sotto una directory di changelog designata, con un'etichetta di eccezione. Il routing per pacchetto e l'inferenza semver per un monorepo possono arrivare dopo; l'abitudine centrale, una voce esiste o qualcuno ha detto esplicitamente che non serve, è quella che vale la pena avere fin dal primo giorno.

Come rifiutare una richiesta senza perdere la cliente

Mon, 07 Sep 2026 00:00:00 GMT

Chiudere il cerchio di solito vuol dire dire a qualcuno che la sua richiesta è stata rilasciata. La metà difficile, per cui la maggior parte dei sistemi di tracciamento non ha alcun processo, è dire di no. La maggior parte delle richieste di funzionalità non viene mai rilasciata, il che significa che la maggior parte della chiusura del cerchio che un prodotto deve davvero alle sue utenti è un rifiuto, non un annuncio, e un rifiuto gestito male costa più buona volontà di quanto ne sarebbe costato il silenzio. Gestito bene, può costare quasi nulla, perché ciò che chi fa una richiesta vuole davvero, il più delle volte, è sapere di essere stata ascoltata, non la funzionalità in sé.

Perché rifiutare bene conta quanto rilasciare bene?

Perché il silenzio si legge come un rifiuto senza spiegazione, e un no spiegato si legge come attenzione. Chi non sente nulla presume che la richiesta sia stata ignorata o persa, ed entrambe le conclusioni le insegnano a smettere di disturbarsi a chiedere, che è lo stesso risultato che un prodotto ottiene con un rifiuto vero e proprio, solo raggiunto più lentamente e con più risentimento lungo la strada. Una risposta che dice no, chiaramente e con un motivo, chiude il cerchio in modo completo quanto una funzionalità rilasciata, e lo fa più in fretta.

Risposta	Cosa impara chi ha chiesto	Costo per il rapporto
Silenzio	Nessuno ha letto, o a nessuno importa	Alto, e cresce con ogni richiesta futura
Risposta automatica senza motivo	È in coda da qualche parte, a tempo indeterminato	Medio; guadagna tempo ma non fiducia
Rifiuto con motivo	È stata letta, considerata e risposta	Basso, se il motivo è onesto
Rifiuto con alternativa	Il bisogno reale è stato davvero ascoltato	Il più basso; spesso costruisce fiducia

Cosa fa atterrare male un rifiuto?

Quasi sempre tre cose, in combinazione. Genericità: un "grazie per il feedback" preconfezionato che non fa riferimento a cosa è stato davvero chiesto si legge come non letto affatto, anche se lo era. Ritardo: un rifiuto che arriva sei mesi dopo la richiesta, quando chi ha chiesto se l'è ormai dimenticato, sembra peggio di un no rapido, perché implica che la richiesta sia rimasta ferma invece di essere stata considerata e rifiutata. E un motivo che non regge: "non è nella nostra roadmap" non risponde a nulla, mentre "questo richiederebbe riprogettare come funzionano i permessi, e non intendiamo toccarli quest'anno" dà a chi ha chiesto qualcosa che può davvero valutare e, se conta abbastanza, far scalare o aggirare.

Cosa dovrebbe dire davvero un buon rifiuto?

Quattro cose, in quest'ordine: un riconoscimento che nomina la richiesta specifica, non una parafrasi generica; il motivo reale, dichiarato onestamente anche quando il motivo onesto è "questo non si adatta a dove sta andando il prodotto" invece di una scusa più morbida; se la porta è chiusa o semplicemente non è aperta ora, perché servono toni molto diversi; e, quando esiste, un'alternativa che affronta il bisogno sottostante anche se non è la funzionalità richiesta alla lettera.

Ciao Jamie,

Grazie per la richiesta di aggiungere l'importazione CSV in blocco per
gli inviti al team. L'abbiamo valutata, e non la costruiremo: il nostro
flusso di invito si basa sulla revisione individuale di ogni nuovo
membro per motivi di sicurezza, e l'importazione in blocco andrebbe
contro questo per progettazione, non per svista.

Se il vero problema è invitare rapidamente un team numeroso, l'API
supporta inviti individuali via script, che ti dà quasi tutta la
velocità senza saltare la revisione: [link]. Fammi sapere se vuoi
aiuto per configurarlo.

Nota cosa fa questo che un modello non può: nomina la funzionalità reale, dà un motivo legato a una vera decisione di design invece che a una politica vaga, e offre un percorso che risolve il problema sottostante invece di chiudere solo il ticket.

In cosa differisce dal chiudere il cerchio su una funzionalità rilasciata?

La meccanica è simile, il tono no. Chiudere il ciclo di feedback con il cliente copre il caso rilasciato, dove il messaggio è una buona notizia e il rischio principale è dimenticarsi di inviarlo. Un rifiuto è una cattiva notizia, o almeno non quella desiderata, e ha bisogno di più cura nel motivo dato e meno automazione nella consegna: una notifica di funzionalità rilasciata può essere un commento preconfezionato innescato da un cambio di stato, ma un rifiuto che si legge come preconfezionato è esattamente il fallimento che questo intero approccio vuole evitare. I due condividono un requisito, però: la richiesta originale deve restare collegata a chi l'ha fatta, la stessa disciplina di tracciamento coperta da tracciamento delle richieste di funzionalità, altrimenti non c'è modo di inviare nessuno dei due messaggi individualmente.

Un rifiuto dovrebbe essere pubblico, come uno stato su una roadmap pubblica?

Di solito non il motivo specifico, anche se lo stato sì. Roadmap pubblica copre le etichette di stato che chi ha chiesto può controllare senza chiedere di nuovo, e uno stato "rifiutato" o "non pianificato" può far parte di quel sistema. Ma il motivo dettagliato, specie quando tocca priorità interne o contesto poco lusinghiero, di solito vale di più nella risposta individuale che in una pagina di stato pubblica, dove la stessa formulazione deve funzionare per ogni lettrice invece che per l'unica persona che ha davvero chiesto.

Ogni richiesta rifiutata merita una risposta individuale?

Ogni richiesta da una persona nominata e raggiungibile sì, almeno breve. Richieste ad alto volume, duplicate o anonime sono l'eccezione: raggruppare richieste simili e rispondere una volta per gruppo, o aggiornare un'etichetta di stato condivisa, è ragionevole quando le risposte individuali davvero non scalano. La linea da mantenere è che "non possiamo rispondere a tutti individualmente" dovrebbe essere un vincolo operativo reale, verificato contro il volume effettivo, non una scusa predefinita per saltare una risposta che avrebbe richiesto due minuti.

FAQ

È meglio rifiutare rapidamente con un motivo debole, o prendersi tempo per uno buono? Rapidamente, con un motivo onesto, batte entrambi presi separatamente. Una risposta rapida con un motivo vero, anche breve, supera una risposta lenta con uno rifinito; il ritardo stesso è parte di ciò che danneggia la fiducia.

Un rifiuto dovrebbe mai promettere di rivalutare la richiesta più avanti? Solo se è davvero probabile e c'è un meccanismo per rivalutarla davvero, come un'etichetta che la fa riemergere a un ciclo di pianificazione. Un vago "lo terremo presente" senza tale meccanismo è funzionalmente uguale al silenzio, solo formulato più gentilmente.

E se il motivo onesto è qualcosa che l'azienda non può condividere, come una preoccupazione competitiva? Dillo direttamente invece di inventare un motivo più morbido. "Non possiamo condividere il ragionamento specifico qui, ma non è qualcosa che pianifichiamo di costruire" è più onesto, e più rispettato, di una spiegazione inventata che crolla davanti a una domanda di approfondimento.

Rifiutare una richiesta significa che dovrebbe essere cancellata dal tracciamento? No. Tienila, etichettata come rifiutata con il motivo, così fa parte del pattern contro cui viene raggruppata la prossima richiesta simile, e così un contesto cambiato più avanti (una nuova integrazione, una nuova priorità di team) può farla riemergere invece di ripartire da zero con la valutazione.

Release notes per i feature flag: cosa dire, e quando

Mon, 07 Sep 2026 00:00:00 GMT

Chiudere il ciclo su una richiesta di funzionalità presuppone un momento netto in cui la cosa è stata rilasciata. Un feature flag elimina quel momento, ed è per questo che scegliere quando pubblicare le release notes per i feature flag è difficile. Il codice viene mergiato, il flag esiste, e per giorni o settimane dopo la funzionalità è contemporaneamente live in produzione e invisibile per quasi chiunque potrebbe volerla usare, spesso inclusa la persona che l'aveva richiesta in origine. Avvisare troppo presto la fa imbattere in una funzionalità che ancora non c'è. Avvisare troppo tardi fa sì che il ciclo che doveva costruire fiducia si legga, invece, come dimenticato.

Perché un flag rompe la solita sequenza "rilascialo, avvisa"?

Perché divide un evento in almeno due: il codice che diventa live, e il flag che viene attivato per un account specifico. Ogni processo per chiudere un ciclo di feedback presuppone che questi accadano insieme, il che è vero per la maggior parte dei rilasci e falso per qualsiasi cosa dietro a un flag usato per rollout graduale, targeting o come interruttore di emergenza. Chiudere il ciclo di feedback del cliente descrive l'avvisare chi ha fatto la richiesta nel momento esatto in cui una voce di changelog viene approvata e pubblicata; quel passaggio è scritto per il caso in cui pubblicare la voce e l'usabilità della funzionalità siano lo stesso momento, e un flag è esattamente il caso in cui non lo sono.

Momento	Cosa è vero	Bisogna già avvisare chi ha fatto la richiesta
Codice mergiato, flag spento ovunque	La funzionalità esiste, nessuno può usarla	No
Flag acceso per l'account di chi ha richiesto	La funzionalità esiste, quella persona specifica può usarla	Sì
Flag acceso per una percentuale di rollout che la esclude	La funzionalità esiste, quella persona ancora non può usarla	No
Flag rimosso del tutto, la funzionalità è semplicemente attiva	La funzionalità esiste per tutti	Sì, se non già avvisato

Qual è la regola vera per sapere quando avvisare qualcuno?

Avvisa quando il flag è acceso per il suo account, non quando il codice viene mergiato e non quando il flag viene creato. Questa singola regola copre ogni riga della tabella sopra, perché lega l'avviso all'unico fatto che conta davvero per chi ha fatto la richiesta: se può, proprio adesso, andare a usare la cosa. Un avviso legato al merge o alla creazione del flag è in realtà un resoconto di avanzamento ingegneristico, e chi ha richiesto una funzionalità non vuole un resoconto di avanzamento, vuole sapere quando andare a guardare.

Questo significa che chi ha fatto la richiesta ha bisogno di accesso anticipato o speciale?

Non necessariamente, e forzarlo crea un problema tutto suo. Se il flag viene rilasciato gradualmente per motivi di carico o stabilità, spostare un account in cima alla coda solo per chiudere un ciclo più velocemente mina la ragione per cui il rollout è scaglionato in primo luogo. Le opzioni oneste sono: aspettare che l'account di chi ha fatto la richiesta raggiunga il rollout naturalmente e avvisarlo allora, oppure, se l'urgenza lo giustifica, attivargli deliberatamente il flag in anticipo, come una decisione reale di chi possiede il rollout, non come effetto collaterale del voler mandare una notifica.

E se il flag è un interruttore di emergenza, non un meccanismo di rollout?

Allora l'assunzione sicura si capovolge. Un flag pensato per poter disattivare rapidamente una funzionalità, piuttosto che scaglionarne il rilascio, di solito significa che la funzionalità è pensata per essere completamente live appena viene creato, e il flag esiste per sicurezza piuttosto che per sequenza. In quel caso, avvisare chi ha fatto la richiesta al momento del deploy è corretto, come per qualsiasi rilascio senza flag; la presenza del flag è un dettaglio operativo che non dovrebbe cambiare quando il ciclo si chiude. La distinzione che conta è a cosa serve il flag, non se ne esiste uno.

Il flag cambia cosa dovrebbero dire le release notes per il feature flag?

Cambia quando la voce viene pubblicata, non cosa contiene. Una voce pubblicata nel momento esatto in cui il flag è acceso per il 100% degli account si legge esattamente come una normale voce di changelog, ed è giusto così; chi la trova più tardi non ha motivo di sapere che un flag sia mai stato coinvolto. Quello che non dovrebbe fare è essere pubblicata mentre il flag è acceso solo per una piccola percentuale di rollout, perché una voce pubblica di changelog manda chiunque la legga, inclusi gli account senza il flag, a cercare una funzionalità che non troveranno, il che è una versione peggiore dello stesso problema, su scala di tutto il prodotto invece che sulla scala di chi ha fatto la richiesta. Quella regola sul tempismo è tutta la differenza tra le release notes per un feature flag e una voce ordinaria: il contenuto è lo stesso, cambia solo la data di pubblicazione. Come scrivere release notes copre la disciplina del "nessuna azione necessaria" che si applica anche qui: chi legge deve sapere se questo lo riguarda, non solo che esiste da qualche parte.

Le email di aggiornamento prodotto dovrebbero trattare diversamente una funzionalità con flag?

Sì, soprattutto ritardandola invece di riscriverla. Il template dell'email di aggiornamento prodotto copre le notifiche mirate contro i digest ampi; una funzionalità con flag è un caso in cui il tempismo di una notifica mirata va verificato contro lo stato del flag della destinataria prima di essere inviata, cosa che un digest ampio non può fare facilmente affatto, il che è un motivo in più per cui un digest è il canale sbagliato per qualsiasi cosa ancora a metà rollout.

FAQ

Bisogna dire a chi ha fatto la richiesta che la sua funzionalità "arriverà presto" quando il flag esiste ma non è ancora acceso per lei? Solo se c'è una data reale e vicina, e anche allora con parsimonia. Un "presto" senza data si legge, passato abbastanza tempo, esattamente come il silenzio, e crea una seconda promessa che va anche lei tracciata e mantenuta.

Chi decide quando un flag è abbastanza avanti da chiudere il ciclo? Chi possiede il rollout, non chi possiede la notifica. Chi ha il rollout sa se il "100% degli account" è imminente o ancora a settimane di distanza; legare il passaggio di chiusura del ciclo al suo stato, invece che a una data fissa, mantiene onesto l'avviso.

Una funzionalità dietro un flag permanente (mai rimosso del tutto) riceve mai una voce pubblica di changelog? Sì, appena raggiunge qualunque cosa significhi "disponibilità generale" per quel prodotto, anche se il flag stesso resta nel codice per sempre per ragioni operative. La voce di changelog riguarda la disponibilità per chi legge, non il dettaglio implementativo di come quella disponibilità è realizzata.

E se il flag viene rimosso e la funzionalità viene eliminata invece di essere rilasciata? Quello è un rifiuto, non un avviso di rilascio, e merita la stessa cura di qualsiasi altro rifiuto. Come rifiutare una richiesta di funzionalità copre cosa dovrebbe dire quel messaggio; chiudere il ciclo onestamente a volte significa chiuderlo con un no.

Le release notes per un feature flag hanno bisogno di un template separato da una voce normale? Nessun cambio di template, solo un passaggio di controllo prima della pubblicazione: verificare lo stato del flag per l'account che ha fatto la richiesta, non solo che il codice sia stato mergiato, e trattenere la voce finché quel controllo non passa. Tutto il resto della voce, la formulazione, la lunghezza, la disciplina delle FAQ, resta uguale a qualsiasi altra release note.

Quando una richiesta di funzionalità è in realtà un bug

Mon, 07 Sep 2026 00:00:00 GMT

"Potete aggiungere un'impostazione per aumentare il limite di esportazione?" si legge come una richiesta di funzionalità, e la maggior parte dei sistemi di triage la etichetta così sul posto. A volte lo è. A volte l'esportazione fallisce a un numero sotto il limite documentato per colpa di un bug, e la cliente, incapace di vedere il codice, ha inventato la soluzione più plausibile che sa descrivere: datemi un numero più grande e forse funzionerà. Quali etichette valgono la pena copre l'etichetta di tipo che divide un backlog in richieste di funzionalità e bug; questo è il caso in cui le parole stesse di una cliente puntano l'etichetta nella direzione sbagliata, e il costo di sbagliare è una deriva lenta verso un backlog pieno di richieste che nessuno vuole davvero una volta guardato sotto.

Come si presenta una richiesta di funzionalità che in realtà è un bug?

Nomina un workaround invece del problema. Una richiesta di funzionalità genuina di solito descrive un risultato che il prodotto non supporta affatto: "lasciatemi programmare questo per dopo", "aggiungete una modalità scura". Un bug mal classificato descrive un numero, una soglia o un comportamento specifico che suona come un'impostazione mancante ma in realtà è un sintomo: "aumentate il timeout", "aggiungete un'opzione di retry", "lasciatemi esportare più righe alla volta". Il segnale è che chi chiede propone un'implementazione, un'impostazione, un interruttore, un override, invece di descrivere un obiettivo, perché ha già provato la funzionalità come documentata e non ha fatto quello che la documentazione dice che dovrebbe fare.

Segnale	Richiesta di funzionalità	Bug travestito da richiesta di funzionalità
Cosa descrive chi chiede	Un risultato che il prodotto non può fare	Un parametro che vuole cambiare
Se il comportamento documentato copre già questo	No, davvero mancante	Sì, ma non funziona come documentato
Se più sforzo fa sparire la richiesta	No	A volte, se il bug dipende da una soglia
Dove dovrebbe essere instradato	Backlog di prodotto	Coda dei bug

Perché questo conta più di quanto sembri?

Perché le due code hanno responsabili, tempistiche e criteri di successo diversi, e un bug archiviato come richiesta di funzionalità viene prioritizzato contro le richieste di funzionalità, competendo per l'attenzione con lacune di prodotto reali invece di essere risolto secondo la tempistica che un bug merita. Come tracciare le richieste di funzionalità copre perché mescolare bug e funzionalità in una sola coda lascia che le lamentele più rumorose spostino le richieste reali; una richiesta di funzionalità che in segreto è un bug fa il danno opposto, resta nel backlog di prodotto accumulando voti per una "funzionalità" che sparirebbe non appena il bug sottostante venisse risolto, il che spreca il segnale di prioritizzazione per chiunque legga quel backlog.

Come si distingue quando le parole stesse della cliente puntano nella direzione sbagliata?

Chiedete cosa si aspettava che succedesse, non cosa vuole che aggiungiate. "L'esportazione si è fermata a 500 righe e me ne servono 2.000, potete alzare il limite" suona come una richiesta di funzionalità di aumento del limite finché la domanda di follow-up, "500 è il limite documentato", non rivela che il numero documentato era 5.000 e l'esportazione fallisce in anticipo. Quella sola domanda, cosa si aspettava contro cosa è successo, fa la maggior parte del lavoro di classificazione, perché una richiesta di funzionalità genuina non ha un comportamento documentato a cui viene meno; non c'è niente da aspettarsi perché la capacità ancora non esiste.

Dovrebbero decidere gli agenti di supporto o le ingegnere?

Gli agenti di supporto fanno il primo passaggio, perché vedono il ticket per primi, ma l'etichetta dovrebbe essere facile da cambiare ed economica da sbagliare, non una decisione una tantum che fissa l'elemento nella coda sbagliata per sempre. Un secondo controllo leggero, un'ingegnera che scandaglia settimanalmente le nuove etichette "richiesta di funzionalità" per qualcosa che puzza di bug travestito, cattura quelle che un agente di supporto senza contesto sul codice non avrebbe potuto riconoscere. Non deve essere formale; è più uno sguardo di cinque minuti che un processo di revisione.

Chiudere il ciclo cambia una volta trovato il bug vero?

Sì, e migliora il messaggio che potete inviare. Chiudere il ciclo di feedback del cliente copre l'avvisare chi ha chiesto quando qualcosa viene rilasciato; un bug ricategorizzato riceve una versione migliore di quel messaggio, perché "abbiamo trovato e risolto il bug dietro a questo" suona come competenza, mentre "abbiamo costruito la funzionalità che avete chiesto" sarebbe stato vero solo per caso, perché la vera richiesta di funzionalità, un limite di esportazione davvero più alto, potrebbe non venire mai costruita una volta che il bug è sparito e il limite originale di 5.000 righe basta.

Cosa succede se la classificazione sbagliata non viene mai colta?

Il backlog si riempie di richieste che sembrano domanda reale e non lo sono, e le decisioni di prioritizzazione prese contro quel backlog ereditano la distorsione. Una "funzionalità" con quaranta voti potrebbe in realtà essere quaranta persone che incontrano lo stesso bug, e costruire la richiesta letterale, un'impostazione per alzare un limite che non era mai stato davvero il vincolo, consegna complessità che non risolve niente, mentre il bug sottostante continua a generare nuove "richieste di funzionalità" da clienti che non hanno ancora trovato questo thread.

FAQ

Vale la pena aggiungere un passaggio formale per controllare ogni richiesta di funzionalità contro bug noti? Non un passaggio formale, piuttosto un'abitudine: chiunque triagi una nuova richiesta di funzionalità dovrebbe chiedere "il comportamento documentato afferma già di fare questo" prima di applicare l'etichetta, perché quella sola domanda cattura la maggior parte delle classificazioni sbagliate senza aggiungere sovraccarico di processo.

E se la cliente insiste che è una richiesta di funzionalità anche dopo che il bug è stato trovato? Spiegate cosa avete trovato e perché l'impostazione che proponeva non servirebbe più una volta risolto il bug. La maggior parte delle clienti chiede un workaround perché ha assunto che la vera soluzione non fosse disponibile, non perché volesse specificamente quell'impostazione.

Un elemento ricategorizzato perde i voti o i commenti che ha accumulato come richiesta di funzionalità? Dovrebbe conservarli, visibili, perché quei voti sono la prova che ha portato a trovare il bug in primo luogo, e nascondere quella traccia rende più difficile cogliere la stessa classificazione sbagliata la prossima volta, su un ticket diverso.

Può succedere al contrario, un bug che in realtà è una richiesta di funzionalità? Meno spesso, ma sì: "questo è rotto" a volte significa "questo non fa quello che ho assunto che facesse", che è una capacità mancante, non un difetto. La stessa domanda, cosa si aspettava contro cosa è documentato, classifica anche in questa direzione.

Come tracciare le richieste di funzionalità senza perderle

Mon, 07 Sep 2026 00:00:00 GMT

Il tracciamento delle richieste di funzionalità fallisce quasi sempre in uno di due modi. O le richieste non hanno un posto dove andare, quindi vivono in caselle di posta e thread Slack dove vengono dimenticate una a una, oppure hanno un posto dove andare che nessuno riguarda più, quindi vengono dimenticate tutte insieme. Un sistema che funziona deve reggere entrambi i fallimenti: serve un unico luogo dove ogni richiesta atterra, e una ragione per riaprire quel luogo il mese prossimo.

Da dove arrivano davvero le richieste di funzionalità?

Da più canali di quanti la maggior parte dei sistemi di tracciamento preveda. Un ticket di supporto che include un "sarebbe bello se". Un commento su una roadmap pubblica. Una chiamata di vendita in cui una potenziale cliente nomina l'unica cosa che blocca l'accordo. Un widget nel prodotto. Ogni canale ha una propria responsabile e propri strumenti, ed è proprio per questo che le richieste si disperdono: la coda ticket del supporto e il backlog del team prodotto raramente sono lo stesso sistema, e una richiesta che raggiunge solo uno dei due ha, di fatto, raggiunto solo un reparto.

Origine	Responsabile tipica	Dove tende a scomparire
Ticket di supporto	Team supporto	Chiuso come risolto, mai più ripreso
Chiamate di vendita	Vendite / account management	Un campo del CRM che nessuno in prodotto legge
Widget nel prodotto	Prodotto	Un form inviato senza follow-up
Commenti sulla roadmap	Chi ha costruito la roadmap	Il thread di commenti stesso
Social media / recensioni	Marketing o nessuno	Catturato in uno screenshot una volta, poi sparito

Un unico form di raccolta per ogni canale non funziona, perché nessuno lo adotta. Quello che funziona è una destinazione in cui ogni canale confluisce, anche se il routing sono cinque minuti al giorno di copia e incolla finché non viene automatizzato.

Cosa rompe davvero il tracciamento delle richieste?

Quasi sempre due cose. La prima è una destinazione mancante: le richieste vengono risposte nel canale in cui sono arrivate e mai registrate da nessuna parte in modo duraturo, per cui la stessa richiesta di tre clienti diversi sembra tre risposte isolate e scollegate invece di un unico segnale. La seconda, più comune, è una destinazione che si riempie e smette di essere letta. Un foglio di calcolo con 400 righe senza filtro non è più un sistema di tracciamento; è un archivio che risulta essere scrivibile.

Il secondo fallimento è il più pericoloso, perché sembra che il tracciamento funzioni. Le richieste vengono registrate. Niente sembra rotto finché qualcuno chiede "quante persone hanno chiesto X" e la risposta onesta è "dovremmo leggere tutte le 400 righe per saperlo".

Cosa dovrebbe registrare davvero una richiesta di funzionalità?

Abbastanza per rispondere a tre domande in seguito senza rileggere il messaggio originale: cosa è stato chiesto, possibilmente con le parole di chi ha fatto la richiesta; chi ha chiesto, e come contattarla se la risposta finisce per essere "l'abbiamo costruito"; e cosa servirebbe per capire se è una richiesta comune o un caso isolato. Una citazione testuale conta più di una parafrasi, perché una parafrasi scritta da chi ha smistato la richiesta porta già la sua lettura, ed è proprio quella lettura che una seconda persona non può verificare sei mesi dopo.

Quali etichette valgono la pena?

Due, e rispondono a domande diverse. Un'etichetta di tipo separa una richiesta di funzionalità da un bug report, perché entrambi richiedono responsabili e tempistiche diverse, e mescolarli in una coda sola lascia che le lamentele più rumorose spostino le richieste. Un'etichetta di priorità, mantenuta a un piccolo insieme come low, medium e high, separa "blocca qualcuno nell'uso del prodotto" da "sarebbe carino", perché entrambe meritano tempi di risposta molto diversi e nessuna dovrebbe ereditare il ritmo dell'altra. Mettere correttamente l'etichetta di tipo presuppone che la richiesta sia quello che dice di essere; quando una richiesta di funzionalità è in realtà un bug copre il caso in cui le parole stesse di una cliente puntano quell'etichetta nella direzione sbagliata.

Il triage automatizzato può applicare entrambe nel momento in cui arriva la richiesta. In changeloop, un invio dal widget riceve l'etichetta feature-request o bug e un'etichetta priority:low|medium|high nello stesso passaggio, più un tag from-widget così l'origine è visibile senza aprire l'elemento. Basta per filtrare il backlog in un minuto invece che in un pomeriggio: mostrami ogni richiesta di funzionalità ad alta priorità arrivata dal widget questo mese.

Una terza etichetta vale la pena appena esiste una roadmap pubblica: uno stato che chi ha fatto la richiesta può controllare da solo. Roadmap pubblica copre per intero gli stati planned, building e shipped; in breve, quell'etichetta trasforma una coda privata in qualcosa che chi ha fatto la richiesta può consultare senza chiedere di nuovo.

Come si decide cosa costruire dopo?

Raggruppare prima di contare. Dieci richieste formulate in modo diverso per la stessa capacità sottostante si leggono come dieci righe disperse in un foglio di calcolo, e come un segnale forte appena raggruppate, e quel raggruppamento è di solito il passaggio mancante, non il conteggio. Un conteggio grezzo senza raggruppamento tende a premiare la funzionalità con il nome più accattivante, non quella con più domanda reale dietro.

Pesare in base a chi chiede, non solo a quanti chiedono. Una richiesta da un account vicino al rinnovo porta un'urgenza diversa dalla stessa richiesta da una registrazione di prova, e un sistema di tracciamento che scarta questo contesto a favore di un conteggio nudo sta ottimizzando per il numero più facile da calcolare, non per quello più utile.

Ogni decisione qui produce anche richieste che perdono, e anche quelle meritano una risposta; come rifiutare una richiesta copre cosa dire a chi ha fatto una richiesta che non ce l'ha fatta. Raggruppare e pesare è solo metà di "cosa costruire dopo"; come dare priorità alle richieste di funzionalità copre i framework veri, RICE, ponderazione per fatturato e conteggi grezzi, e dove ognuno si rompe.

Come si chiude il cerchio una volta rilasciato qualcosa?

Questo è il passaggio che i sistemi di tracciamento saltano più spesso, ed è quello che chi ha fatto la richiesta nota davvero. Chiudere il ciclo di feedback con il cliente copre la meccanica per intero; ciò che conta qui è che chiudere il cerchio funziona solo se la richiesta originale è rimasta collegata a chi l'ha fatta. Un template di richiesta di funzionalità costruito da un issue GitHub, con l'identità di chi ha chiesto legata all'issue invece che sepolta in un commento, è ciò che rende possibile una notifica automatica di "rilasciato" invece di una che qualcuno deve ricordarsi di inviare. Template di richiesta di funzionalità mostra il template concreto e a cosa serve ogni campo.

FAQ

Che strumento dovrei usare per tracciare le richieste di funzionalità? Ciò che il team già controlla ogni giorno batte qualsiasi strumento dedicato che nessuno apre. Un tracker di issue GitHub funziona bene se l'ingegneria vive già lì; una board leggera funziona bene se il prodotto vive lì. Lo strumento conta meno del fatto che venga riaperto.

Come evito che le richieste di funzionalità si duplichino? Raggruppare per capacità sottostante prima di smistare per formulazione. Una ricerca tra le richieste esistenti prima di aprirne una nuova intercetta la maggior parte dei duplicati; un passaggio mensile di raggruppamento intercetta il resto. Unire i duplicati senza perdere la voce originale copre cosa fare con la formulazione una volta fatto il raggruppamento in sé, così la fusione non restringe silenziosamente la richiesta a qualunque segnalazione sia arrivata per prima.

Ogni richiesta di funzionalità dovrebbe ricevere una risposta? Ognuna dovrebbe ricevere una conferma, anche breve, ma non ognuna ha bisogno di una decisione subito. Uno stato visibile, come un'etichetta di roadmap che chi ha chiesto può controllare da solo, sostituisce la maggior parte delle risposte individuali che un team dovrebbe altrimenti.

Qual è la differenza tra tracciamento delle richieste e roadmap pubblica? Il tracciamento è il registro interno di ogni richiesta, incluse quelle che non verranno mai rilasciate. Una roadmap pubblica è il sottoinsieme a cui un team si impegna pubblicamente, con uno stato che chi ha fatto la richiesta può vedere senza chiedere di nuovo.

Ticket di supporto vs. richieste: di cosa ti fidi?

Mon, 07 Sep 2026 00:00:00 GMT

Una bacheca di richieste di funzionalità cattura ciò che le utenti chiedono quando hanno tempo di sedersi e descrivere cosa vogliono. Un ticket di supporto cattura in cosa sono bloccate le utenti proprio adesso, spesso infastidite, spesso senza il vocabolario per descrivere pulitamente la richiesta sottostante. Entrambi sono segnale reale, e i team che guardano solo uno dei due finiscono per risolvere il problema sbagliato con sicurezza, perché ogni canale sovrarappresenta sistematicamente un tipo diverso di utente e un tipo diverso di bisogno. Dare priorità alle richieste di funzionalità copre come classificare ciò che è già in bacheca; questo riguarda il divario tra ciò che arriva in bacheca e ciò che compare solo mai come ticket di supporto.

Perché lo stesso problema sottostante comparirebbe in un canale e non nell'altro?

Perché i due canali hanno costi di attivazione diversi, e la dimensione di quel costo determina chi lo supera. Presentare una richiesta di funzionalità richiede iniziativa: un'utente deve credere che la richiesta valga la pena di essere articolata, trovare la bacheca, e scrivere qualcosa di coerente, il che seleziona utenti coinvolte e pazienti già investite nel prodotto. Presentare un ticket di supporto richiede quasi nessuna iniziativa a confronto, spesso solo un clic su "aiuto" a metà di un compito, il che significa che cattura utenti frustrate nel momento, incluse quelle che non si sarebbero mai disturbate con una bacheca di richieste. Un divario reale nel prodotto può essere invisibile sulla bacheca funzionalità e rumoroso nel supporto semplicemente perché le utenti che ci si imbattono sono quelle meno propense a presentare una richiesta formale.

Il volume di ticket per una funzionalità mancante significa la stessa cosa del conteggio voti per essa?

No, perché misurano popolazioni diverse in condizioni diverse. Una richiesta di funzionalità con cento voti rappresenta cento persone che si sono prese il tempo di trovare e sostenere una richiesta esistente, il che è un segnale forte di domanda durevole e ponderata. Cento ticket di supporto sullo stesso divario sottostante, presentati nello stesso periodo, probabilmente rappresentano utenti che sbattono contro un muro nel momento, alcune delle quali dimenticherebbero del tutto una volta passata la frizione immediata. Trattare i due come segnale equivalente di "cento persone lo vogliono" sovrappesa il volume di ticket, perché i ticket sono economici da generare e i voti no.

Bacheca richieste	Ticket di supporto
Richiede iniziativa per presentare	Ne richiede quasi nessuna
Cattura domanda ponderata e durevole	Cattura frustrazione nel momento
Sbilanciata verso utenti coinvolte e pazienti	Cattura utenti che non userebbero mai la bacheca
Un conteggio voti è un vero segnale di impegno	Un conteggio ticket riflette frizione, non sempre desiderio

Cosa significa quando una funzionalità ha ticket di supporto ma quasi nessun voto in bacheca?

Spesso, che la richiesta esiste ma le utenti che ci si imbattono non sanno che la bacheca esiste, non credono che votare serva a qualcosa, o incontrano il problema troppo raramente per disturbarsi a cambiare canale per registrarlo formalmente. Questa è esattamente la popolazione che una bacheca richieste perde strutturalmente, e un conteggio voti basso qui è prova di un divario di misurazione, non di domanda scarsa. Trattate un gruppo di ticket di supporto attorno a una funzionalità mancante come un proprio segnale degno di essere registrato voi stessi in bacheca, per conto delle utenti, invece di diffidare dei ticket, così da non restare invisibile a chi dà priorità basandosi solo sui conteggi voti.

La bacheca legge come bassa priorità:
"Export to CSV": 4 voti in 6 mesi

Il supporto racconta una storia diversa:
"Export to CSV": 31 ticket nello stesso periodo, ognuno
da un account diverso, ognuno chiuso con "non
attualmente supportato, passeremo il feedback"

Un picco nei ticket di supporto significa sempre che il problema sottostante è una funzionalità mancante?

No, ed è qui che i due canali possono ingannare nella direzione opposta. Un picco di ticket è altrettanto spesso causato da un'interfaccia confusa attorno a una funzionalità già esistente, da un bug, o da un cambiamento uscito senza spiegazione adeguata, nessuno dei quali si risolve costruendo qualcosa di nuovo. Leggere ogni picco di ticket come "le utenti vogliono una funzionalità che non abbiamo" produce una roadmap piena di cose che erano in realtà divari di documentazione o problemi di usabilità travestiti. Il ticket di supporto vi dice dove sta la frizione; non vi dice da solo se la soluzione è una nuova funzionalità, un cambio di interfaccia, o un articolo di aiuto migliore, e confondere le due cose spreca tempo di ingegneria sulla soluzione sbagliata.

Come dovrebbero essere combinati davvero i due segnali quando si decide cosa costruire?

Usate i ticket per trovare dove sta la frizione, e usate la bacheca richieste, più il contatto diretto dove la bacheca è scarna, per confermare come appare davvero il risultato desiderato. Un gruppo di ticket identifica un problema reale e sentito; raramente specifica la soluzione con precisione sufficiente per costruirci contro, perché un'utente frustrata in una conversazione di supporto descrive sintomi, non specifiche. La bacheca richieste, quando ha abbastanza voti sullo stesso problema sottostante, tende a portare più del dettaglio di "cosa soddisferebbe davvero questo", perché scrivere una richiesta è già un atto di specificare cosa si vuole, non solo segnalare cosa non va.

Le agenti di supporto dovrebbero registrare i ticket come richieste di funzionalità loro stesse?

Sì, ed è la correzione a maggior leva singola per il divario tra i due canali. Un'agente che riconosce un ticket come una richiesta di funzionalità travestita, invece di limitarsi a risolverlo e andare avanti, può registrarlo in bacheca per conto della cliente, il che chiude direttamente il divario di misurazione invece di richiedere che la cliente scopra e usi un secondo canale. Questo funziona solo se registrarlo richiede secondi, non minuti, per l'agente, così che la frizione di farlo sia inferiore alla frizione di chiudere semplicemente il ticket e passare al successivo.

FAQ

I voti delle richieste di funzionalità dovrebbero mai essere scontati se vengono tutti da un solo account o team? Sì, pesate per account o organizzazioni distinte invece che per conteggio grezzo di voti, perché cinque voti da cinque persone della stessa azienda rappresentano le priorità di una cliente, non cinque conferme indipendenti di domanda.

Vale la pena costruire una funzionalità che compare molto nei ticket ma ha quasi nessun voto? Spesso sì, purché il volume di ticket venga genuinamente da account distinti e il bisogno sottostante sia confermato invece che assunto; trattate il basso conteggio voti come un artefatto di misurazione del costo di attivazione della bacheca, non come prova che la domanda non sia reale.

Come si distingue a colpo d'occhio un ticket di confusione UI da un genuino ticket di funzionalità mancante? Guardate se la risoluzione consiste nello spiegare una capacità esistente o nello scusarsi per una mancante. Un pattern di risoluzioni "oh, in realtà è proprio lì" indica un problema di interfaccia o scopribilità; un pattern di "non lo supportiamo ancora" indica un divario reale.

Questa distinzione conta altrettanto con un volume di supporto molto piccolo? Meno meccanicamente, dato che una manciata di ticket è facile da leggere individualmente senza bisogno di analisi aggregata, ma il bias sottostante, i ticket sovrarappresentano utenti frustrate e sottorappresentano quelle pazienti, è presente a qualsiasi scala e vale la pena tenerlo a mente anche quando leggete ogni ticket voi stessi.

Tag git, release e il tuo changelog

Mon, 07 Sep 2026 00:00:00 GMT

Un tag git, una release e una voce di changelog sono tre registrazioni diverse dello stesso evento, e confonderli fa deragliare silenziosamente un changelog da ciò che è stato davvero rilasciato. Un tag marca un commit. Una release impacchetta quel tag con artefatti e una descrizione. Una voce di changelog spiega, in termini che una lettrice fuori dal repository può usare, cosa è cambiato. Di solito accadono vicini nel tempo, ed è proprio per questo che è facile trattarli come un unico passaggio invece di tre, ed è proprio per questo che il divario diventa visibile solo mesi dopo, quando qualcuno chiede "cosa è stato rilasciato nella v2.4" e la risposta onesta richiede una vera ricerca.

Qual è la differenza reale tra i tre?

Registrazione	Vive in	Scritta per
Tag git	Il repository, come riferimento	Chi fa checkout di quel commit esatto
Release	L'host del codice (GitHub, GitLab)	Chi scarica una build
Voce di changelog	Il changelog del prodotto stesso	Chi usa il prodotto, non solo il repo

Un tag è il più meccanico dei tre: git tag v2.4.0 e basta, senza alcun requisito che qualcosa spieghi cosa contiene. Una release aggiunge una descrizione e, di solito, artefatti scaricabili, e il suo pubblico rimane sviluppatrici che sanno cos'è una pagina di release. Una voce di changelog è l'unica delle tre scritta per una lettrice che potrebbe non aprire mai il repository, motivo per cui è quella che richiede più attenzione editoriale e quella più facilmente saltata sotto pressione di scadenze.

Ogni tag git ha bisogno di una voce di changelog?

No, e trattarli come uno a uno è un errore comune. Un tag può segnare una milestone interna, una release candidate, o un hotfix che non raggiunge mai la maggior parte delle utenti; nessuno di questi ha necessariamente bisogno di una voce pubblica. Il test è lo stesso che decide se qualcosa appartiene affatto a un changelog: se un'utente o chi chiama lo noterebbe o gliene importerebbe. La maggior parte dei tag passa questo test. Alcuni, come un tag creato solo per innescare una pipeline CI, mai.

Ogni voce di changelog ha bisogno del proprio tag?

Non sempre, ed è qui che i team che fanno deploy continuo divergono dai team che rilasciano pacchetti versionati. Un prodotto SaaS che fa più deploy al giorno può raggruppare più deploy sotto una voce di changelog datata senza un tag 1:1 per ogni deploy; una libreria pubblicata in un registro di pacchetti ha di solito bisogno di un tag per versione pubblicata. I moduli Go e Swift Package Manager risolvono le versioni direttamente dai tag; su npm o PyPI è il registro a conservare la versione pubblicata, e il tag è il modo in cui chiunque riconduce quella versione al suo sorgente. Un repository con più pacchetti versionati in modo indipendente deve deciderlo per pacchetto, non una volta sola per tutto il repo; changelog nei monorepo copre come i prefissi dei tag e l'ambito del changelog dovrebbero seguire i confini dei pacchetti, non delle cartelle. Semantic versioning e il tuo changelog copre come il numero di versione stesso dovrebbe mappare sulle categorie del changelog; i tag sono il meccanismo che rende un numero di versione verificabile contro il codice reale.

Come dovrebbe relazionarsi una descrizione di release con la voce di changelog?

Possono essere lo stesso testo, ma solo se il pubblico di entrambi è davvero lo stesso, il che è più raro di quanto sembri. Una pagina di release su un host di codice viene letta quasi esclusivamente da sviluppatrici; se un prodotto ha anche utenti non tecnici che leggono il changelog, duplicare la descrizione della release parola per parola manda termini interni e una formulazione orientata al codice a una lettrice che aveva bisogno della versione in linguaggio semplice. Lo schema più pulito: scrivere la voce di changelog come l'artefatto principale orientato alla lettrice, e lasciare che la descrizione della release la colleghi oppure mantenga un riassunto più breve e tecnico per il pubblico già a suo agio lì.

# Release v2.4.0 (GitHub, per sviluppatrici)
Aggiorna la pipeline dei report al nuovo motore di aggregazione. Vedi
il changelog per il riassunto orientato al cliente:
https://example.com/changelog#v2.4.0

## 2026-09-07 (Changelog, orientato al cliente)
### Added
- I report ora si caricano in meno di un secondo, anche per account
  con più di un milione di righe.

Stessa release, due documenti, ognuno con la propria formulazione per la propria lettrice.

Da dove viene davvero la voce di changelog?

Da due punti di partenza, e la maggior parte delle pipeline reali è un misto di entrambi. Può essere generata dai messaggi di commit al momento del tag, il che è veloce e non perde mai una pull request unita; dai conventional commit al changelog copre quella pipeline per intero. Oppure può essere scritta a mano, separata dal tag, sincronizzata con il momento in cui una funzionalità è considerata pronta invece che con il momento in cui il codice viene unito. Le voci generate sono coerenti ma ereditano ogni messaggio di commit vago; le voci scritte a mano sono più chiare ma richiedono qualcuno che le scriva davvero. La maggior parte dei team che automatizza mantiene comunque un leggero passaggio di editing sul testo generato prima che diventi la voce pubblica, la stessa disciplina che raccomanda Keep a Changelog, in pratica, indipendentemente da dove sia originariamente venuto il testo grezzo.

Cosa si rompe quando i tre si desincronizzano?

La fiducia in quello che la lettrice ha controllato per prima. Un tag che esiste senza una voce di changelog corrispondente sembra, dal lato di chi legge il changelog, che quella settimana non sia successo nulla. Una voce di changelog senza tag o release corrispondente rende impossibile per chi sta facendo debug di un problema in produzione fare checkout del codice esatto che era live quando è stata pubblicata una voce. La soluzione non è l'automazione perfetta, è un'unica fonte di verità per la corrispondenza: un posto, anche solo la checklist stessa del processo di release, che dica che un cambiamento rilasciabile riceve tutti e tre, nello stesso commit o pull request che lo introduce.

FAQ

Le voci di changelog dovrebbero essere generate automaticamente dai tag git? Possono essere un punto di partenza, ma un tag da solo non porta nessuna descrizione orientata alla lettrice, solo un intervallo di commit. La generazione automatizzata deve leggere i messaggi di commit dentro quell'intervallo, non solo l'esistenza del tag, per produrre qualcosa di utilizzabile.

E se non taggiamo ogni release? Allora la voce di changelog diventa la registrazione principale, e dovrebbe comunque portare una data e, se il prodotto ne ha una, un numero di versione, così la voce resta qualcosa a cui una lettrice può fare riferimento più tardi anche senza un tag corrispondente.

I tag pre-release (come v2.4.0-rc.1) dovrebbero avere voci di changelog? In generale no. Una release candidate è per test interni o beta, e una voce di changelog per essa insegna alle lettrici ad aspettarsi voci per versioni che potrebbero non essere mai rilasciate così come descritte. Riserva le voci ai tag che raggiungono la disponibilità generale.

Una singola voce di changelog può coprire più tag git? Sì, e spesso dovrebbe per i team che taggano frequentemente. Raggruppa tag correlati sotto una voce datata che descriva il cambiamento netto, invece di pubblicare una voce sottile per tag che frammenta una funzionalità su più letture.

Changelog di API interne: cosa cambia per l'altro team

Mon, 07 Sep 2026 00:00:00 GMT

Ogni altro articolo di questo hub presuppone che chi chiama un'API sia fuori dall'azienda: la sviluppatrice di una cliente, una partner, qualcuno che ha trovato la documentazione da solo. Molte API hanno un tipo di chiamante completamente diverso, un team nella stanza accanto o a due piani di distanza, e questo cambia il calcolo di cosa un changelog gli deve, perché un messaggio Slack lo raggiunge e di solito non viene mai aperto un ticket di supporto. La maggior parte dei team ne conclude che le API interne non hanno bisogno di un changelog. Quello di cui hanno davvero bisogno è uno diverso.

Cosa rende diverso il changelog di un'API interna da quello di una pubblica?

Il pubblico è raggiungibile direttamente, il che elimina il motivo principale per cui esistono la maggior parte dei changelog di API pubbliche: trasmettere a chiamanti che non si possono contattare individualmente. Il team proprietario di un'API interna di solito sa esattamente quali altri team la chiamano, a volte fino al servizio specifico. Questo rende un messaggio mirato, non un feed pubblico, la scelta predefinita naturale, ed è per questo che le API interne finiscono così spesso senza alcun changelog: il team proprietario avvisa i due o tre team che ricorda, assumendo che questo copra tutti.

	Changelog di API pubblica	Changelog di API interna
Chi lo legge	Qualsiasi chiamante esterno, per lo più irraggiungibile direttamente	Un insieme piccolo e di solito noto di team interni
Canale predefinito	Una pagina e un feed	Un messaggio ai team chiamanti, idealmente anche una pagina
Rischio maggiore	Un chiamante si perde completamente la voce	Il team proprietario dimentica un chiamante di cui non ricorda l'esistenza
Cosa sostituisce "non sappiamo chi ci chiama"	Niente; pubblicare ampiamente	Un registro reale dei chiamanti, tenuto aggiornato

Perché "avviseremo semplicemente i team che ci chiamano" fallisce?

Perché l'insieme dei chiamanti non è mai così piccolo o statico come lo ricorda il team proprietario. Un servizio costruito per un consumatore guadagna un secondo chiamante sei mesi dopo, tramite un'integrazione che nessuno ha annunciato, e la lista mentale "chi ci chiama" del team proprietario ora è sbagliata senza che nessuno se ne accorga. Il fallimento è ordinario e comune, il risultato predefinito dell'affidarsi alla memoria invece che a un registro, non il segno che qualcuno è stato disattento. Cos'è un breaking change copre come decidere se un cambiamento di API conta come rompente in primo luogo; il caso interno aggiunge una seconda domanda più difficile sopra quella, ovvero sapere chi avvisare.

Un'API interna ha bisogno comunque di una pagina di changelog in stile pubblico?

Di solito sì, anche se il canale primario è diretto. Una pagina dà al messaggio diretto qualcosa a cui collegarsi, così la notifica può essere breve ("breaking change su /v2/accounts, dettagli qui") invece di provare a portare l'intera spiegazione in un messaggio di chat che scorrerà via. Diventa anche ciò che un nuovo team, o uno che si è perso il messaggio diretto, può controllare quando la sua integrazione si rompe e cerca di capire perché. La pagina non deve essere rifinita o pubblica; deve essere collegabile e deve sopravvivere al thread Slack che l'ha annunciata.

Chi mantiene davvero l'elenco dei chiamanti?

Il team proprietario, e va trattato come un artefatto reale, non come conoscenza tribale. La versione più economica è un file nel repository stesso dell'API, un breve elenco di servizi consumatori con una responsabile per voce, aggiornato ogni volta che viene costruita una nuova integrazione, la stessa disciplina di qualsiasi dichiarazione di dipendenza. L'alternativa, chiedere in giro prima di ogni breaking change, funziona finché una volta qualcuno non si dimentica di chiedere alla persona giusta, e un'API interna che si rompe silenziosamente per un team è un incidente più piccolo di uno pubblico, ma resta un incidente, di solito scoperto dal reperibile di quel team stesso piuttosto che dalla proprietaria dell'API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Un file così trasforma "chi dobbiamo avvisare" da una domanda in una ricerca. Strumenti costruiti esattamente per questo problema, come il catalogo servizi di Backstage, modellano le API come entità di prima classe con consumatori dichiarati per lo stesso motivo: una volta che un'organizzazione ha abbastanza servizi interni, la memoria di nessuno su chi chiama cosa resta accurata da sola, e qualcosa deve tenere il registro al suo posto. La documentazione dello strumento che già usate internamente è di solito il posto giusto da controllare prima di costruirne uno su misura.

Cosa appartiene a una voce di changelog interna che una pubblica non avrebbe bisogno?

Più specificità operativa, perché chi legge è un'altra ingegnera che agirà su questo all'interno della stessa infrastruttura, non lo leggerà come un riassunto. In quali ambienti è live il cambiamento e quando, perché i servizi interni spesso vengono promossi attraverso stadi che un chiamante pubblico non vede mai. Se il cambiamento richiede un aggiornamento di configurazione o di libreria client lato consumatore, formulato come un comando se ne esiste uno. E, poiché i chiamanti interni spesso possono coordinare la correzione direttamente con il team proprietario, un contatto nominato invece di un canale di supporto: "avvisa @maria se questo rompe qualcosa" è una riga perfettamente ragionevole in una voce interna e una strana in un changelog di API pubblica.

Questo vale allo stesso modo per un changelog dentro un monorepo?

Acuisce lo stesso problema invece di sostituirlo. Changelog monorepo copre quando un pacchetto ha bisogno del proprio changelog; un'API interna che è uno dei tanti pacchetti in un monorepo ha comunque bisogno che i suoi consumatori siano tracciati esplicitamente, perché condividere il repository con chi la chiama non significa che questi noteranno un cambiamento a meno che qualcosa non glielo indichi. La vicinanza nel repo non è la stessa cosa della vicinanza nell'attenzione.

FAQ

Un'API solo interna ha bisogno di un changelog se ha un unico chiamante? A malapena, e un messaggio diretto a quell'unico team di solito basta. Il changelog si giustifica appena c'è più di un chiamante, o appena l'elenco dei chiamanti ha sorpreso una volta il team proprietario, perché quello è il segnale che la memoria da sola non è più affidabile.

I cambiamenti di API interni dovrebbero passare per la stessa revisione di quelli pubblici? La formulazione può essere più leggera, perché chi legge è una collega e non una chiamante esterna, ma la decisione se un cambiamento è rompente merita la stessa cura in entrambi i casi. Una chiamante interna ha comunque codice in produzione che dipende dal comportamento precedente.

Come si scopre chi chiama un'API interna se non è mai stato tracciato? I log del server o i dati di traffico di una service mesh sono la risposta onesta se non è mai stato mantenuto un registro dei consumatori; tratta quella scoperta come il momento di iniziarne uno, non come una pulizia una tantum.

Un messaggio Slack basta, o un cambiamento interno ha comunque bisogno di una voce di changelog formale? Entrambi, per qualsiasi cosa non sia puramente additiva. Il messaggio è ciò che viene letto in tempo; la voce è ciò che un team che indaga un problema settimane dopo, e non ha mai visto il messaggio, può comunque trovare.

Release note interne: chi altro deve sapere cosa è uscito

Mon, 07 Sep 2026 00:00:00 GMT

Ogni altro articolo di questo hub presuppone che chi legge una release note sia una cliente. Supporto, vendite e customer success leggono anche loro, o ci provano, e la maggior parte scopre cosa è uscito perché una cliente lo chiede per prima. Quest'ordine è invertito, ed è anche l'impostazione predefinita nella maggior parte delle aziende, perché il processo di release finisce nel momento in cui esce la nota rivolta ai clienti, e nessuno ha costruito un secondo passaggio, più piccolo, per chi deve rispondere a domande su di essa un'ora dopo.

Cos'è una release note interna, e come si differenzia da una rivolta ai clienti?

È un documento più breve, scritto per persone che già conoscono a fondo il prodotto, che dice loro cosa è cambiato e cosa fare al riguardo nel loro lavoro concreto. Un agente di supporto non ha bisogno della cornice curata che usa un annuncio rivolto ai clienti; deve sapere come appare il cambiamento nel prodotto in questo momento, quale sarà la domanda più probabile a riguardo, e se ci sono ticket aperti coinvolti. Una nota rivolta ai clienti vende il cambiamento. Una interna equipaggia qualcuno a gestirlo.

Pubblico	Cosa deve sapere	Dove ne ha bisogno
Supporto	Cosa è cambiato nell'interfaccia, domande probabili, ticket aperti coinvolti	Dove già cerca le risposte
Vendite	Cosa sblocca per un affare, cosa non fa ancora	Dove si prepara alle chiamate
Customer success	Cosa dire alle clienti esistenti, e chi lo ha chiesto	Dove pianifica i contatti
Direzione	Cosa è uscito rispetto a quanto promesso, e quando	Un riepilogo breve e ricorrente, non per ogni release

Perché i team interni scoprono i lanci in ritardo?

Perché il processo di release di solito è costruito attorno a un solo artefatto, la nota rivolta ai clienti o la voce di changelog, e si presuppone che tutto ciò che è interno segua dalla lettura di quel documento. Non è così. Gli agenti di supporto sono occupati con il ticket che hanno davanti, non a sfogliare un changelog in cerca di contesto, e una nota scritta per una cliente spesso omette proprio il dettaglio operativo di cui ha bisogno un agente, come a quale piano è vincolata la funzionalità o come appare il messaggio di errore quando fallisce. Quando una cliente chiede, l'agente sta leggendo la stessa nota pubblica che la cliente ha appena letto, senza alcun vantaggio.

Cosa dovrebbe dire una release note interna che una rivolta ai clienti non dice?

I dettagli operativi che una nota rivolta ai clienti lascia fuori di proposito. Quali piani o account ce l'hanno. Come appare quando qualcosa va storto, e cosa dire a una cliente che ci si imbatte. Se chiude qualche richiesta o ticket aperto, e quali, così un agente che lavora su un ticket collegato sa di doverlo controllare. Chi nel team se ne assume la responsabilità se una domanda va oltre quanto copre la nota. Nulla di tutto questo appartiene alla versione rivolta ai clienti, scritta per essere letta una volta da qualcuno fuori dall'azienda; tutto questo è proprio ciò di cui ha bisogno chi risponde alla stessa domanda quaranta volte a settimana.

Nota interna: esportazione CSV in blocco (esce 08-09-2026)

- Limitata ai piani Team ed Enterprise. Free e Pro non vedono
  cambiamenti.
- Errore comune: le esportazioni oltre 50k righe vanno in timeout;
  problema noto, correzione tracciata separatamente. Dire alla
  cliente di filtrare per intervallo di date.
- Chiude 14 richieste aperte etichettate `bulk-export`. Template
  di risposta nel documento condiviso.
- Responsabile: team platform, #platform-eng per tutto ciò che
  va oltre questa nota.

Quattro righe che un agente di supporto può usare subito, nessuna delle quali apparterebbe alla voce pubblica del changelog per la stessa funzionalità.

Chi dovrebbe scriverla, e quando?

Chi scrive la nota rivolta ai clienti di solito è la persona giusta, perché ha già tutto il contesto, ma dovrebbe essere un passaggio breve e separato invece di provare a far servire un solo documento a entrambi i pubblici. Unirle produce una nota rivolta ai clienti appesantita da dettagli interni, oppure una nota interna troppo curata per essere davvero utile, ed è più veloce nella pratica scrivere due documenti brevi che negoziare un documento solo perché serva due pubblici alla volta. Il tempismo conta più dell'autorship: la nota interna deve uscire prima di quella rivolta ai clienti, anche solo di qualche ora, così il supporto non scopre mai un cambiamento nello stesso posto di una cliente.

Dove dovrebbe stare perché il supporto la trovi davvero nel momento di un ticket?

Dove il team già cerca le cose quando arriva un ticket, non in un changelog separato che nessuno ha motivo di aprire di propria iniziativa. Un team di supporto che usa una base di conoscenza condivisa ha bisogno della nota lì, collegata da dove i ticket su quella parte del prodotto sono già etichettati. Un team che vive in un canale condiviso ne ha bisogno pubblicata lì, cercabile, nel momento in cui è rilevante, invece che sepolta in un riepilogo quotidiano che sfogliano una volta. Lo schema rivolto ai clienti di notifica mirata contro digest si applica anche qui: una nota interna su un cambiamento specifico e imminente dovrebbe raggiungere direttamente il team, non aspettare un riepilogo settimanale che arriva dopo che il primo ticket esiste già.

Serve lo stesso rigore di revisione di quella esterna?

Meno, ed è voluto. Una nota rivolta ai clienti rappresenta l'azienda pubblicamente e merita un passaggio di editing accurato; una nota interna esiste per essere veloce e concreta, e sottoporla allo stesso standard di rifinitura è di solito proprio ciò che porta i team a smettere di scriverla del tutto. Una nota interna rapida e un po' grezza che esce un'ora prima del lancio batte una rifinita che arriva il giorno dopo, quando il primo ticket di supporto è già arrivato confuso.

FAQ

Le release note interne dovrebbero passare per lo stesso processo di approvazione di quelle rivolte ai clienti? No. Un passaggio più leggero e veloce è proprio l'obiettivo. Richiedere la stessa revisione trasforma una nota interna dello stesso giorno in una della settimana successiva, quando il supporto ha già risposto alla domanda senza di essa.

Chi è responsabile delle release note interne se non c'è un ruolo dedicato alla comunicazione interna? Chi scrive la nota rivolta ai clienti, come secondo passaggio breve subito dopo. Non serve una responsabile separata, solo l'abitudine di non trattare la nota rivolta ai clienti come l'unico artefatto che produce una release.

Le release note interne hanno bisogno di un proprio changelog o archivio? Un posto cercabile batte un archivio cronologico che nessuno scorre. Se il supporto ha già una base di conoscenza, la nota appartiene lì, etichettata alla funzionalità, invece che in un changelog interno separato che aiuta solo chi già sa la data in cui è uscita.

Qual è il rischio di saltare le release note interne per i cambiamenti piccoli? I cambiamenti piccoli sono proprio quelli per cui il supporto riceve domande senza preavviso, perché un cambiamento piccolo raramente riceve un annuncio a livello aziendale. La dimensione della release note dovrebbe scalare con la dimensione del cambiamento; non dovrebbe mai scendere a zero solo perché il cambiamento era minore.

Changelog nei monorepo: uno solo, o uno per pacchetto?

Mon, 07 Sep 2026 00:00:00 GMT

Un monorepo ospita più cose rilasciabili separatamente in un solo repository, e un changelog deve prima rispondere a una domanda: al lettore interessa il repo, o gli interessa un pacchetto specifico al suo interno? La maggior parte dei team non lo decide mai apposta. Iniziano con un changelog perché c'è un repo, aggiungono pacchetti via via, e finiscono con un log dove chi usa la CLI deve scorrere quaranta voci del backend che non gli interessano per trovare quella che ha rilasciato la sua correzione. Ciò che decide la forma giusta non è la struttura del repository, ma chi legge il log e cosa già sa di cercare.

Cosa rende diverso il changelog di un monorepo da quello di un repo singolo?

Un changelog di repo singolo ha un pubblico implicito: chiunque usi l'unica cosa che quel repo costruisce. Il pubblico di un monorepo si divide per pacchetto, e i pacchetti nello stesso repo spesso vengono rilasciati con calendari diversi, a consumatori diversi, con livelli di stabilità diversi. Una libreria pubblicata in un registro e uno strumento amministrativo interno possono convivere nello stesso monorepo e non avere quasi nulla in comune per chi legge il changelog.

Forma del repo	Lettore tipico	Changelog adatto
Una singola app rilasciabile	Chiunque usi il prodotto	Un log, per tutto il repo
Workspace di librerie (più pacchetti pubblicati)	Chi dipende da un pacchetto specifico	Un log per pacchetto
App più strumenti interni	Due pubblici diversi senza sovrapposizione	Diviso per pubblico, non per cartella
App più il proprio SDK	Utenti del prodotto, e integratori dell'SDK	Due log: uno per il prodotto, uno per l'SDK

Ogni pacchetto ha bisogno del proprio changelog?

Solo quelli con un pubblico indipendente. Un pacchetto pubblicato in un registro ha bisogno del proprio log, perché chi lo installa non ha motivo di leggere altro nel repo, e gli strumenti di rilascio per monorepo come Lerna e Changesets scrivono un CHANGELOG.md per pacchetto, accanto al suo package.json. Un'utility interna con un solo consumatore, l'app già presente nello stesso repo, non ha bisogno di un log separato; incorporare i suoi cambiamenti nelle voci di quell'app è più utile di un secondo file che nessuno fuori dal team apre.

Il test è lo stesso che decide se una voce qualsiasi appartiene a un changelog: il lettore lo noterebbe o gli interesserebbe, e può agire sapendolo. Applicalo per pacchetto, non per cartella, e un repo con dodici pacchetti può finire con due changelog veri e dieci pacchetti che semplicemente non ne hanno bisogno.

Come si sa quale pacchetto ha causato quale voce di changelog?

Etichetta ogni voce con il suo pacchetto nel momento in cui viene scritta, non dopo, ispezionando quali file ha toccato un commit. Un commit che corregge una libreria interna condivisa può produrre una voce di changelog in ogni pacchetto che ne dipende, e i percorsi dei file da soli non possono dire quale di queste voci a valle il lettore debba davvero vedere; solo una persona che decide "questo è visibile a chi usa il pacchetto A e non a chi usa il pacchetto B" può farlo. I conventional commits aiutano qui meccanicamente, nominando il pacchetto in ogni commit, ma lo scope produce comunque solo una bozza. La stessa regola a due livelli di quell'articolo si applica per pacchetto: una bozza con lo scope giusto ha comunque bisogno di un passaggio umano prima di essere scritta per il lettore reale di quel pacchetto.

Cosa serve a un changelog condiviso che uno di repo singolo non richiede?

Un'etichetta di pacchetto su ogni voce, all'inizio, prima della descrizione, così chi scorre il log può saltare in un solo passaggio tutto ciò che non lo riguarda. Senza quell'etichetta, un log condiviso si legge come un feed casuale, e chi si interessa a un pacchetto non ha modo di filtrarlo se non memorizzare quali righe contano, cosa che nessuno fa dopo la prima settimana.

## 2026-09-07

### [cli] Aggiunto
- `acme push --dry-run` mostra cosa verrebbe inviato senza
  inviarlo davvero.

### [core] Corretto
- Il backoff dei retry non si azzera più con una richiesta
  riuscita che restituisce un corpo vuoto.

Due voci, due pubblici, un'occhiata per distinguerle. Un flusso in stile Changesets integra questa etichettatura direttamente nel processo di release: chi contribuisce scrive una nota breve, con lo scope del pacchetto, insieme alla propria modifica, e lo strumento assembla i changelog per pacchetto e i salti di versione da quelle note al momento della release, invece di provare a ricostruire i confini dei pacchetti a posteriori da una cronologia di commit unificata.

Come si intreccia il versioning con un changelog di monorepo?

I pacchetti versionati in modo indipendente hanno bisogno del proprio changelog perché hanno un proprio numero di versione, e un changelog condiviso non può esprimere "il pacchetto A è passato da 2.1 a 2.2 mentre il pacchetto B è rimasto a 1.4" senza diventare due log dentro un file. Semantic versioning e il tuo changelog copre come un numero di versione dovrebbe mappare sulle categorie del changelog; in un monorepo quella mappatura va applicata per pacchetto, perché un breaking change in un pacchetto non lo è per un pacchetto gemello che non ne dipende.

Un repo che rilascia un prodotto come un'unica unità rilasciabile, anche se costruito da molti pacchetti interni, non ha questo problema: i pacchetti condividono la versione perché vengono sempre rilasciati insieme, e un changelog unico è corretto.

Come si inseriscono i tag git in un monorepo?

Vale la stessa regola di tag git, release e il tuo changelog, applicata per pacchetto: un pacchetto con versione propria ha bisogno del proprio prefisso di tag, tipicamente nome-pacchetto@1.4.0 invece di un v1.4.0 nudo che non può dire a quale pacchetto appartiene. Un monorepo taggato solo con numeri di versione nudi non può poi rispondere "cosa c'era in core quando cli ha rilasciato la 2.2", perché nulla su disco registra a quale pacchetto appartenesse davvero quel tag.

FAQ

Serve un changelog separato per ogni pacchetto di un monorepo? Solo per i pacchetti con pubblico indipendente, di solito qualsiasi cosa pubblicata in un registro. Un pacchetto con un solo consumatore interno già presente nello stesso repo può confluire nel log di quel consumatore invece di mantenerne uno proprio.

Cosa etichetta una voce di changelog con il pacchetto giusto? Chi scrive la voce, nel momento in cui la scrive, non una scansione automatica dei percorsi di file modificati. Un cambiamento in una libreria condivisa può produrre una voce diversa in ogni pacchetto che ne dipende, e solo una persona può decidere cosa dovrebbe davvero dire ciascuna di quelle voci a valle.

Un monorepo dovrebbe usare un unico numero di versione per tutto? Solo se ogni pacchetto viene sempre rilasciato insieme agli altri. Se i pacchetti vengono mai pubblicati in modo indipendente, hanno bisogno di versioni indipendenti, e le versioni indipendenti hanno bisogno di changelog indipendenti per avere senso.

Uno strumento per il changelog di un monorepo sostituisce il passaggio di editing umano? No. Strumenti come Changesets automatizzano la raccolta e l'assemblaggio delle note per pacchetto al momento della release; la nota in sé, scritta nel linguaggio del lettore invece che di chi contribuisce, resta comunque compito di una persona, come in qualsiasi altra pipeline di changelog.

Come annunciare una nuova funzionalità (senza silenzio)

Mon, 07 Sep 2026 00:00:00 GMT

La maggior parte degli annunci di funzionalità muore in un canale che nessuno legge due volte: un tweet che scorre via, un'email del giorno del rilascio sepolta sotto le altre dodici ricevute da un'iscritta quella settimana, un messaggio Slack in un canale che metà del team ha silenziato mesi fa. La funzionalità è stata rilasciata. Quasi nessuno che l'avrebbe usata lo ha scoperto. Risolvere questo ha meno a che fare con lo scrivere un annuncio migliore e più con lo scegliere il canale giusto per la lettrice giusta, e raggiungere direttamente chi l'ha chiesta esplicitamente invece di contare sul fatto che noti un annuncio generico.

Dove dovrebbe essere annunciata davvero una nuova funzionalità?

In più di un posto, perché "tutti leggono lo stesso canale" non è mai vero. Una voce di changelog o feed serve la lettrice che controlla secondo i propri tempi e vuole il registro permanente e datato. Un avviso in-app serve la lettrice che sta già usando il prodotto e userebbe la funzionalità oggi stesso se sapesse che esiste. L'email serve la lettrice che non è attualmente nel prodotto ma tornerebbe per l'aggiornamento giusto. I social servono la copertura oltre le utenti esistenti, quasi senza targeting.

Canale	Ideale per	Debolezza
Changelog / feed	Il registro permanente; lettrici che controllano ai propri tempi	Passivo; non fa nulla per chi non controlla mai
Avviso in-app	Utenti già presenti che agirebbero oggi	Non raggiunge chi non è connesso al momento
Email	Utenti non attive che tornerebbero per questo	Facile da seppellire sotto altra posta; serve un oggetto vero
Social	Copertura oltre le utenti attuali	Quasi nessun targeting; vita breve

Nessuno dei quattro basta da solo. Il changelog è l'unico documento che dovrebbe portare ogni rilascio a prescindere dalla dimensione, perché è il registro a cui tutto il resto rimanda; gli altri tre sono amplificazione aggiunta sopra, scelta in base a quanto è davvero grande la funzionalità.

Cosa dovrebbe dire per primo l'annuncio?

Il risultato, non il meccanismo. "Abbiamo aggiunto un layer di cache all'endpoint dei report" descrive cosa ha costruito il team. "I report ora si caricano in meno di un secondo" descrive cosa è cambiato per la lettrice, ed è la frase che porta al click, perché risponde a "cosa ci guadagno" nella prima proposizione invece che nella terza. Il meccanismo appartiene alla voce di changelog o alla pagina di dettaglio, non al titolo.

Dati concreti prima degli aggettivi. "Un'esperienza report più veloce e potente" non dice alla lettrice nulla su cui agire; "i report ora si caricano in meno di un secondo e si possono filtrare per stato" le dice esattamente cosa è cambiato e cosa provare. La seconda versione risulta anche più credibile, perché un'affermazione vaga suona esattamente come suona il testo di marketing quando non c'è niente di concreto da dire.

In cosa differisce da un'email di aggiornamento prodotto?

Sovrapposti ma non identici. Email di aggiornamento prodotto copre il canale email nello specifico, inclusi cadenza, oggetti, e quando un digest batte un invio singolo. Un annuncio di nuova funzionalità è l'evento sottostante; l'email è uno dei quattro canali sopra che potrebbe portarlo, scelto quando la funzionalità è abbastanza grande da giustificare un invio dedicato invece di viaggiare nel prossimo digest. Una funzionalità piccola si guadagna una voce di changelog e forse un avviso in-app. Una significativa si guadagna tutti e quattro i canali, coordinati nel tempo.

Come si raggiungono le persone specifiche che l'hanno chiesta?

Questo è l'annuncio con il miglior rapporto tra sforzo e risultato, e quasi tutti i team lo saltano. Se dieci clienti hanno chiesto una funzionalità per nome, quelle dieci persone meritano una nota diretta e personale nel momento in cui viene rilasciata, indipendentemente da qualsiasi annuncio più ampio in uscita. Chiudere il ciclo di feedback con il cliente copre la meccanica per intero; il riassunto qui è che funziona solo se la richiesta originale è rimasta collegata a chi l'ha fatta, che è più un problema di tracciamento che un problema di annuncio. In changeloop, quando un feedback dal widget è diventato un issue GitHub e la pull request mergiata lo chiude (fixes #142), approvare la voce di changelog pubblica su quell'issue il commento "Shipped — ", una sola volta, con un link alla voce live, e chi ha inviato il feedback vede la voce rilasciata nel widget. Nessuno deve ricordarsi di dirglielo. Gli issue aperti a mano, e i repository GitLab o Bitbucket, non ricevono il commento.</p> <h2>Come si scrive la voce stessa?</h2> <p>La stessa disciplina di qualsiasi altra voce di note di rilascio: iniziare con cosa può fare ora chi legge, seguire con la configurazione necessaria, saltare la giustificazione interna. <a href="https://changeloop.dev/blog/it/how-to-write-release-notes/">Come scrivere note di rilascio</a> copre il metodo completo; un annuncio di nuova funzionalità è il caso con la posta più alta, perché è la voce con più probabilità di essere catturata in uno screenshot, inoltrata, e letta da chi non ha mai visto il changelog del prodotto.</p> <h2>Quando non conviene annunciare ampiamente?</h2> <p>Quando la funzionalità è ancora in rollout verso un sottoinsieme di account, è davvero una beta, o ha un prezzo o un blocco tale che nove lettrici su dieci di un annuncio ampio non potrebbero ancora usarla. Un annuncio ampio per una funzionalità che nove lettrici su dieci non possono usare si legge come un'esca, e brucia la fiducia nel prossimo annuncio più di quanto costruisca entusiasmo in questo. La soluzione non è il silenzio, è la portata: informare direttamente gli account idonei e trattenere i canali ampi finché la disponibilità non raggiunge l'annuncio.</p> <h2>FAQ</h2> <p><strong>Ogni nuova funzionalità merita il proprio annuncio?</strong> Ognuna si guadagna una voce di changelog. Solo quelle abbastanza significative da cambiare come qualcuno usa il prodotto, o quelle chieste esplicitamente per nome, si guadagnano i canali più ampi come email o social.</p> <p><strong>Qual è il canale migliore per una funzionalità piccola?</strong> Solo il changelog, più un avviso in-app se la funzionalità è scopribile dentro un flusso in cui l'utente si trova già. Email e social valgono la pena per funzionalità che giustificano il chiedere attenzione.</p> <p><strong>Come si annuncia una funzionalità alle persone che l'hanno specificamente chiesta?</strong> Mantenere la richiesta collegata a chi l'ha fatta dal momento in cui viene registrata, poi notificare individualmente al rilascio, separatamente da qualsiasi annuncio più ampio. Un'etichetta di stato condivisa che chi ha chiesto può controllare da solo riduce anche quanti messaggi individuali servono in primo luogo.</p> <p><strong>Un annuncio di funzionalità ha bisogno di uno screenshot?</strong> Per qualsiasi cosa visiva, sì; una funzionalità descritta ma non vista viene saltata molto più spesso di una di cui le lettrici possono vedere un'anteprima. Per un'API o una capacità backend, un breve esempio di codice svolge lo stesso lavoro di uno screenshot per un cambiamento UI.</p> </article> <article> <h1>Release notes per app mobile: cosa taglia il limite</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Tutto in questo hub su come scrivere release notes presuppone una pagina che controlli completamente: qualsiasi lunghezza, link che funzionano, formattazione che si renderizza. Le release notes di un'app mobile vivono dentro la scatola di qualcun altro. Apple concede circa 4.000 caratteri ma mostra solo le prime righe prima che venga toccato "altro"; Google concede uno spazio simile con lo stesso problema effettivo di anteprima, e nessuna delle due piattaforme renderizza un link cliccabile dentro il testo. Le regole di <a href="https://changeloop.dev/blog/it/how-to-write-release-notes/">come scrivere release notes che le persone leggono davvero</a> valgono ancora: dire cosa è cambiato e cosa deve fare chi legge, ma lo spazio per farlo è una frazione di quello che consente una pagina di changelog, e i tagli devono essere deliberati, non accidentali.</p> <h2>Cosa entra davvero nell'anteprima visibile?</h2> <p>Le prime una o due righe, circa 80-170 caratteri a seconda del dispositivo e della dimensione del font, prima che chi legge debba toccare per espandere. Questo è l'intero budget per la parte della release note che decide se qualcuno leggerà il resto, e significa che la frase più importante deve venire per prima, non il numero di versione, non un saluto, non un'intestazione di categoria. Una release note che inizia con "Novità di questa versione:" ha già speso un terzo del suo spazio visibile in quattro parole che non dicono nulla a chi legge.</p> <table> <thead> <tr> <th>Piattaforma</th> <th>Limite totale approssimativo</th> <th>Anteprima effettiva prima di "altro"</th> </tr> </thead> <tbody><tr> <td>App Store (iOS)</td> <td>~4.000 caratteri</td> <td>2-3 righe, circa 80-170 caratteri</td> </tr> <tr> <td>Google Play</td> <td>~500 caratteri per lingua, alcuni campi più corti</td> <td>2-3 righe, simile a iOS</td> </tr> <tr> <td>Entrambe</td> <td>Nessun link cliccabile nel campo release notes</td> <td>N/D</td> </tr> </tbody></table> <h2>La regola "cosa puoi fare ora, cosa ti si deve" funziona ancora a questa lunghezza?</h2> <p>Sì, e diventa più rigida, non diversa. Una frase per voce, verbo per primo, senza premessa: "Esporta i tuoi dati come CSV da Impostazioni." batte "Abbiamo aggiunto la possibilità per gli utenti di ora esportare i propri dati in formato CSV" usando un terzo delle parole per dire la stessa cosa. Alla lunghezza di una pagina di changelog, una frase un po' prolissa costa a chi legge mezzo secondo. Alla lunghezza di una release note mobile, la stessa prolissità può spingere la frase interamente fuori dall'anteprima visibile, così chi legge non vede mai il verbo che avrebbe detto cosa è cambiato.</p> <pre><code>Male, spreca l'anteprima sulla cornice: "Siamo entusiasti di portarti un nuovo aggiornamento pieno di miglioramenti! Continua a leggere per i dettagli." Bene, tutto il valore nella prima riga: "Esporta i dati come CSV. La modalità scura ora rispetta l'impostazione di sistema. Corretto un crash all'apertura dei link condivisi." </code></pre> <h2>Cosa deve essere tagliato che una voce di changelog web normalmente terrebbe?</h2> <p>I link, per primi, perché nessuno dei due store li renderizza cliccabili, quindi un URL nel testo è peso morto che chi legge dovrebbe ridigitare. Se la voce ha bisogno di una destinazione, di' invece cosa toccare nell'app: "Vedi i nuovi filtri sotto Impostazioni > Ricerca" funziona; "Leggi di più su example.com/blog/filtri" no, su questa superficie. Secondo, qualsiasi cosa condizionale o specifica per un pubblico: un changelog web può dire "se usi l'API, questo ti riguarda", ma un elenco di store raggiunge ogni utente installato contemporaneamente, quindi una riga condizionale si legge come rumore per il 95% a cui non si applica. Metti il dettaglio condizionale in un messaggio in-app invece, attivato per gli account che riguarda davvero.</p> <h2>Ogni rilascio dovrebbe avere le proprie note, o va bene riutilizzare "correzioni di bug e miglioramenti delle prestazioni"?</h2> <p>Riutilizzalo per i rilasci che sono genuinamente questo, ma verifica quanto spesso è davvero vero. <a href="https://changeloop.dev/blog/it/how-to-write-release-notes/">Come scrivere release notes</a> copre già perché quella frase tradisce una nota scritta dall'interno invece che per chi legge; su mobile fa un danno doppio, perché le release notes dello store sono uno dei pochi posti dove alcuni utenti vedono qualcosa tra un aggiornamento e l'altro, e una lunga serie di "correzioni di bug e miglioramenti delle prestazioni" si legge come se l'app non cambiasse, il che è un'impressione peggiore di nessuna nota per quel periodo.</p> <h2>Le release notes influenzano se le persone aggiornano l'app?</h2> <p>Indirettamente, tramite la visibilità più che la persuasione. La maggior parte degli utenti aggiorna automaticamente e non legge mai le note prima di aggiornare; le note contano di più per la minoranza che controlla gli aggiornamenti manualmente, e per chi recensisce o fa stampa e scorre lo storico di un elenco di store. Scrivere per quel pubblico più piccolo comunque ripaga, perché un elenco con uno storico reale di voci specifiche e datate si legge come un'app mantenuta attivamente, e un elenco con un anno di "correzioni di bug e miglioramenti delle prestazioni" no, indipendentemente da quanto sia stato davvero rilasciato in quel periodo.</p> <h2>E un aggiornamento forzato, dove la nota deve spiegare perché l'utente non ha scelta?</h2> <p>Indica il motivo e la scadenza nella prima riga, prima di qualsiasi altra cosa, perché un aggiornamento forzato è l'unico caso in cui chi legge è già infastidito prima di iniziare a leggere. "Questo aggiornamento è necessario per continuare a sincronizzare i tuoi dati. Aggiorna entro il [data] per evitare interruzioni." dice cosa fare e perché in una sola frase; seppellire quella motivazione sotto tre righe di note su funzionalità non correlate si legge come se l'app stesse nascondendo la parte scomoda.</p> <h2>FAQ</h2> <p><strong>Le release notes mobile dovrebbero corrispondere al changelog web dello stesso rilascio?</strong> Coprire gli stessi cambiamenti sottostanti, ma non parola per parola. Il changelog web può permettersi la spiegazione completa; la nota mobile ha bisogno degli stessi fatti compressi in una frase con il verbo per primo, il che di solito significa che è una riscrittura, non una copia.</p> <p><strong>Vale la pena localizzare le release notes mobile per ogni lingua supportata?</strong> Sì, più che per un changelog web, perché l'elenco dello store è spesso l'unica superficie localizzata che alcuni utenti vedono tra una sessione e l'altra, ed entrambe le piattaforme supportano release notes per locale senza lavoro ingegneristico aggiuntivo oltre alla traduzione stessa.</p> <p><strong>Quanto dovrebbe essere lunga una release note mobile se non c'è un limite che forza la brevità?</strong> Corta comunque. Il tetto di 4.000 caratteri su iOS è raramente il vincolo reale; lo è l'anteprima di 2-3 righe, e scrivere oltre quello che quell'anteprima mostra significa solo che meno persone leggono la parte che contava.</p> <p><strong>Le release notes hanno bisogno del numero di versione nel testo visibile?</strong> No. Lo store mostra già il numero di versione accanto alle note. Ripeterlo dentro il testo spende caratteri visibili per informazioni che chi legge ha già davanti.</p> </article> <article> <h1>Dare priorità alle richieste che si accumulano</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Tracciare le richieste di funzionalità risolve dove vivono. Non risolve quale esce per prima, e questa seconda domanda è quella su cui i team restano davvero bloccati. Un backlog con trecento richieste raggruppate ed etichettate ha comunque bisogno di una regola decisionale, perché "costruisci la cosa più richiesta" funziona solo finché due richieste sono vicine e una terza ha una sostenitrice rumorosa, che è la maggior parte delle settimane. I framework qui sotto non sono risposte in competizione alla stessa domanda. Ognuno si adatta a un tipo diverso di richiesta, e usarne uno solo per tutte è di solito il vero errore.</p> <h2>Cosa rende diverso dare priorità alle richieste di funzionalità rispetto a una roadmap?</h2> <p>Una decisione di roadmap parte dalla strategia e chiede cosa costruire. Una decisione su una richiesta di funzionalità parte da una domanda che esiste già e chiede se agire su di essa, e le due tirano in direzioni diverse abbastanza spesso che una richiesta può avere molta domanda ed essere comunque sbagliata da costruire, o avere poca domanda ed essere comunque utile perché sblocca un account strategico. Trattare ogni richiesta come un voto di roadmap salta questo controllo.</p> <table> <thead> <tr> <th>Framework</th> <th>Cosa pesa</th> <th>Dove si rompe</th> </tr> </thead> <tbody><tr> <td>Conteggio grezzo delle richieste</td> <td>Quante persone hanno chiesto</td> <td>Premia i nomi accattivanti sulla domanda reale</td> </tr> <tr> <td>RICE</td> <td>Portata, impatto, fiducia, sforzo</td> <td>Serve stime che nessuno ha per una richiesta appena arrivata</td> </tr> <tr> <td>Ponderato per fatturato</td> <td>Chi ha chiesto, in base al valore dell'account</td> <td>Ignora richieste da account che non valgono ancora molto</td> </tr> <tr> <td>Voti pubblici</td> <td>Segnale visibile, basso sforzo</td> <td>Raggiunge solo utenti che già sanno dove guardare</td> </tr> </tbody></table> <h2>Cos'è RICE, e funziona per le richieste di funzionalità?</h2> <p><a href="https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/">RICE</a> valuta un'idea su portata, impatto, fiducia e sforzo, poi divide i primi tre per il quarto per ottenere un numero confrontabile. È stato costruito per idee di roadmap in cui un team crede già, dove la parte difficile è confrontare scommesse diverse tra loro. Le richieste di funzionalità arrivano già con un numero di portata, il conteggio di chi ha chiesto, che è più concreto della portata che di solito ha un'idea di roadmap appena nata. Dove RICE va in tensione con una richiesta è su fiducia e impatto: un team può essere sicuro che una richiesta sia reale e comunque non avere basi per sapere quanto muoverà una metrica, perché "impatto" per una richiesta che ha già un nome e una traccia di utenti reali è un tipo di stima diverso dall'impatto di un'idea che nessuno fuori dalla stanza ha ancora visto.</p> <p>Usa RICE per le richieste che vengono prese seriamente in considerazione e non ancora decise. Non applicarlo a ogni richiesta in arrivo; lo sforzo di valutazione si ripaga solo su quelle abbastanza vicine da avere bisogno di uno spareggio.</p> <h2>Bisogna pesare per fatturato, o per chi ha chiesto?</h2> <p>Per chi ha chiesto, ma non solo per fatturato. Un account vicino al rinnovo, un account che ha già fatto escalation, e un account la cui richiesta sblocca un affare in corso portano un'urgenza che una cifra di fatturato piatta non cattura da sola, e una richiesta da una registrazione di prova può comunque contare se blocca una decisione che presto diventa fatturato. La ponderazione per fatturato è la più facile da calcolare tra queste, e proprio per questo la più facile su cui riporre troppa fiducia: rimuove correttamente il rumore da account senza vera posta in gioco, e con la stessa facilità può declassare una richiesta che porterebbe un account molto più grande ancora nella pipeline.</p> <h2>Che ruolo giocano davvero i voti?</h2> <p>Un segnale economico e continuo per richieste che esistono già, e un pessimo modo per scoprire quali richieste dovrebbero esistere in primo luogo. Un conteggio di voti raggiunge solo gli utenti che hanno già trovato la richiesta e l'hanno ritenuta degna di un clic, il che significa che il totale dei voti di una roadmap pubblica riflette tanto la visibilità quanto la domanda: una richiesta vecchia vicino in cima alla lista continua ad accumulare voti in parte perché è facile da trovare, e una richiesta più nuova e altrettanto reale parte da zero. L'articolo sulla <a href="https://changeloop.dev/blog/it/public-roadmap/">roadmap pubblica</a> sostiene di lasciare del tutto i voti fuori dalla roadmap. Tratta i voti come un segnale che va raggruppato e pesato per recency, non come una classifica da costruire in ordine. <a href="https://changeloop.dev/blog/it/feedback-signal-quality/">Ticket di supporto vs. richieste</a> copre l'altro punto cieco nei conteggi voti: un divario reale può generare quasi nessun voto se le utenti che ci si imbattono non trovano mai la bacheca, mentre compare rumorosamente nel supporto.</p> <h2>Quando vince la cliente più rumorosa, ed è un problema?</h2> <p>A volte, ed è un problema solo quando nessuno se ne accorge. Una cliente che fa escalation spesso, scrive ticket dettagliati o ha una linea diretta con qualcuno del team vedrà le sue richieste esaminate più in fretta di una cliente più silenziosa con una richiesta altrettanto valida, e un processo di prioritizzazione che non lo verifica mai favorirà sistematicamente chi insiste di più, non chi ha il caso più solido. Le clienti rumorose non sono il problema da correggere; le loro richieste sono spesso genuinamente importanti. La correzione è un'abitudine: passare in rassegna il backlog per origine periodicamente e verificare se lo stesso pugno di account spiega la maggior parte di ciò che è stato rilasciato di recente, e chiedersi se corrisponde a dove sta davvero la domanda.</p> <h2>Come si trasforma una decisione di prioritizzazione in una risposta?</h2> <p>Ogni decisione qui produce vincitrici e perdenti, ed entrambe meritano una risposta che nomini il ragionamento reale, non solo un cambio di stato senza spiegazione. <a href="https://changeloop.dev/blog/it/declining-feature-requests/">Come rifiutare una richiesta di funzionalità</a> copre cosa dire a una richiesta che ha perso, in un modo che mantiene intatta la relazione invece di leggersi come un rifiuto generico. Il lavoro di raggruppamento ed etichettatura che rende possibile tutto questo è coperto in <a href="https://changeloop.dev/blog/it/feature-request-tracking/">tracciare le richieste di funzionalità</a>; la prioritizzazione funziona solo su richieste già registrate e raggruppate abbastanza bene da poter essere confrontate.</p> <h2>FAQ</h2> <p><strong>Qual è il framework migliore per dare priorità alle richieste di funzionalità?</strong> Nessuno da solo. Usa i conteggi grezzi per trovare il segnale più rumoroso, RICE per confrontare una breve lista di candidate serie, e un controllo su fatturato o account per individuare i casi in cui una domanda silenziosa da un account strategico pesa più di un gruppo più rumoroso ma meno importante.</p> <p><strong>Le richieste di funzionalità dovrebbero essere prioritizzate come le idee di roadmap?</strong> No. Le idee di roadmap partono dalla strategia; le richieste di funzionalità partono da una domanda che esiste già. Valutarle insieme fa sì che una scommessa strategica ben argomentata ma con poca domanda esistente perda costantemente contro una richiesta che semplicemente ha più persone che l'hanno chiesta.</p> <p><strong>I voti su una roadmap pubblica riflettono accuratamente la domanda?</strong> Solo tra le persone che hanno già trovato la richiesta. Le richieste più vecchie e visibili accumulano voti più in fretta indipendentemente da quanta domanda reale ci sia dietro una più nuova, quindi tratta i totali dei voti come un segnale, raggruppato e pesato per recency, non come una classifica da costruire in ordine.</p> <p><strong>Con che frequenza andrebbero rivalutate le priorità delle richieste di funzionalità?</strong> Con un ciclo fisso, non solo quando qualcuno fa escalation. Una revisione mensile o trimestrale che riraggruppa le richieste e ricontrolla la ponderazione individua le derive, come un pugno di account che domina ciò che viene rilasciato, che un processo puramente reattivo non fa mai emergere da solo.</p> </article> <article> <h1>Release notes enterprise: cosa cambia per un solo account</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un prodotto SaaS pubblico invia le stesse release notes a tutti, perché tutti sono sulla stessa versione. Una cliente enterprise su una versione fissata, un'istanza dedicata, o un sottoinsieme del prodotto con feature flag rompe quel presupposto: le release notes che descrivono cosa è cambiato per lei non sono le stesse del vostro blog pubblico, e inviarle comunque quelle pubbliche o la confonde con cambiamenti che non ha ancora, o, peggio, le racconta di una funzionalità che l'account team di un'altra cliente enterprise vi ha esplicitamente chiesto di trattenere dalla propria istanza per un altro mese. <a href="https://changeloop.dev/blog/it/release-notes-best-practices/">Buone pratiche per le release notes</a> copre il mestiere generale; questo riguarda come scrivere release notes enterprise per il problema di calibrazione che compare quando avete clienti che non sono tutte sulla stessa build.</p> <h2>Perché una cliente enterprise non può semplicemente leggere il changelog pubblico?</h2> <p>Perché descrive una versione che forse non sta ancora eseguendo, funzionalità a cui forse non ha accesso, e un calendario che non corrisponde al suo. Una cliente fissata a un ciclo di rilascio trimestrale che legge di una funzionalità uscita per il livello pubblico la settimana scorsa non ha modo di sapere, dal solo changelog pubblico, se quella funzionalità le arriverà la settimana prossima o il prossimo trimestre. Il changelog pubblico risponde a "cosa è cambiato nel prodotto"; la domanda reale di una cliente enterprise è "cosa è cambiato nella versione che sto eseguendo, e quando ricevo il resto", cosa che il changelog pubblico non è mai stato scritto per rispondere.</p> <h2>Cosa serve a una release note privata che una pubblica non ha bisogno?</h2> <p>Un identificatore di versione o ambiente contro cui la cliente possa davvero verificare, e una dichiarazione esplicita di cosa non le è ancora arrivato. "Questa versione include i miglioramenti all'export in massa dalla nostra release pubblica 4.3, ma non il nuovo modello di permessi, che arriva nel vostro prossimo aggiornamento programmato" dice a un'amministratrice enterprise esattamente dove si trova la sua istanza rispetto al prodotto in generale. Una release note pubblica non ha mai bisogno di questa cornice perché c'è solo un'istanza a cui essere relativa; una privata è priva di senso senza di essa.</p> <table> <thead> <tr> <th>Release notes pubbliche</th> <th>Release notes private (enterprise)</th> </tr> </thead> <tbody><tr> <td>Una versione, un pubblico</td> <td>Più versioni, pubblici segmentati</td> </tr> <tr> <td>Assume che la lettrice abbia ogni funzionalità descritta</td> <td>Deve dichiarare cosa ha e cosa non ha la lettrice</td> </tr> <tr> <td>Sincronizzate con la release pubblica</td> <td>Sincronizzate con la finestra di aggiornamento propria della cliente</td> </tr> <tr> <td>Si può rendere subito completamente pubblica</td> <td>Potrebbe dover trattenere elementi che altre clienti non hanno ancora</td> </tr> </tbody></table> <h2>Va bene mai semplicemente ritardare l'invio delle release notes pubbliche a clienti enterprise invece di scriverne di separate?</h2> <p>Solo se la loro versione corrisponde davvero a quella pubblica in quel momento, il che è più raro di quanto sembri appena avete più di un paio di account enterprise su ritmi diversi. Ritardare le note pubbliche funziona come soluzione temporanea per una cliente che è indietro di una versione e sta per raggiungerla; si rompe nel momento in cui due clienti enterprise sono su versioni diverse tra loro, perché a quel punto non esiste più un'unica "le note" da ritardare, solo una matrice di cosa ha ciascuna. A quel punto, calibrare le note per account, anche se è solo una vista filtrata delle stesse voci sottostanti, smette di essere opzionale.</p> <pre><code>Note pubbliche, inviate a un account enterprise che non ha ancora la funzionalità: "New: Bulk export now supports custom column ordering." (Confuso: l'admin lo prova e non c'è.) Note enterprise calibrate per lo stesso account: "Available in your next update (scheduled for 2026-10-15): bulk export with custom column ordering. Not yet available on your current version (3.8)." </code></pre> <h2>Chi dentro l'organizzazione della cliente le legge davvero, e questo cambia come si scrive?</h2> <p>Di solito un'amministratrice IT o un contatto customer success invece di un'utente finale, e questo cambia cosa conta come utile. Un'utente finale vuole sapere cosa appare diverso sul suo schermo; un'amministratrice enterprise vuole sapere cosa è cambiato nei permessi, nella gestione dei dati, nella configurazione SSO, o qualsiasi cosa che influisca su come gestisce il deployment per le proprie utenti, perché sarà lei a rispondere alle domande interne. Una release note privata che si legge come un changelog consumer, tutti pulsanti nuovi e lucidi e nessun dettaglio operativo, costringe l'amministratrice a scavare per l'informazione di cui aveva davvero bisogno.</p> <h2>Come interagisce questo con una roadmap pubblica o un changelog pubblico che elenca già la stessa funzionalità?</h2> <p>Con attenzione, perché una cliente che legge entrambi noterà qualsiasi incoerenza. Se il vostro changelog pubblico ha già annunciato una funzionalità che un account enterprise specifico non ha ancora, la sua release note privata deve riconoscere quel divario invece di fingere che la voce pubblica non esista; un'amministratrice che ha visto l'annuncio pubblico e riceve note private che lo ignorano assumerà o che ve ne siete dimenticate di lei, o che qualcosa è rotto. <a href="https://changeloop.dev/blog/it/public-roadmap/">Roadmap pubblica</a> copre come mantenere una roadmap onesta su cosa è uscito rispetto a cosa è pianificato; la versione enterprise di quell'onestà nelle release notes consiste nel nominare direttamente il divario tra ciò che è pubblico e ciò che è suo.</p> <h2>Un'azienda piccola con solo una o due clienti enterprise ha bisogno di tutta questa struttura?</h2> <p>Non del sistema completamente segmentato, ma la disciplina centrale, dichiarare chiaramente su quale versione si trova la cliente e cosa ha e cosa non ha, conta a qualsiasi scala nel momento in cui avete anche solo una cliente che non è sulla vostra build più recente. Il modo di fallimento che questo previene, un'amministratrice confusa sul fatto che un annuncio pubblico si applichi a lei, costa un ticket di supporto e un colpo alla fiducia indipendentemente dal fatto che abbiate due account enterprise o duecento.</p> <h2>FAQ</h2> <p><strong>Le release notes private dovrebbero mai menzionare funzionalità che altre clienti hanno già ma questa no?</strong> Solo se è rilevante per il suo proprio calendario, espresso come "arriva nel vostro prossimo aggiornamento" invece che come confronto con altre clienti. Nominare cosa ha una specifica altra cliente attraversa un territorio che non spetta a voi rivelare; nominare cosa arriva specificamente a questa cliente è esattamente l'informazione di cui ha bisogno.</p> <p><strong>Le stesse voci di changelog sottostanti possono alimentare sia le note pubbliche che quelle private?</strong> Sì, ed è di solito l'approccio più sostenibile: etichettate le voci con quali versioni o livelli si applicano, poi filtrate per pubblico al momento della pubblicazione invece di scrivere due documenti completamente separati che inevitabilmente divergono.</p> <p><strong>Cosa succede se una cliente enterprise chiede esplicitamente di essere sulle release notes pubbliche invece che su un feed privato?</strong> Rispettatelo, ma confermate che capisce che le note pubbliche presuppongono la versione pubblica, e segnalate voi stessi per iscritto il divario se la sua versione diverge da quanto descritto. Quella conferma scritta è ciò che vi protegge dopo se agisce in base a note pubbliche che in realtà non si applicavano alla sua build.</p> <p><strong>Con quanto anticipo dovrebbe essere avvisata una cliente enterprise di una funzionalità a cui avrà accesso nella prossima release?</strong> Non appena la data è confermata, non solo al momento del rilascio, perché le amministratrici enterprise spesso devono pianificare la propria comunicazione interna o formazione attorno a una funzionalità in arrivo, e una notifica lo stesso giorno non lascia loro margine per farlo.</p> </article> <article> <h1>Semantic versioning e il tuo changelog</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Il semantic versioning dice a chi chiama quanto può fargli male una release prima di leggere una singola voce del changelog. Passare da <code>2.4.1</code> a <code>2.5.0</code> dice: nuova capacità, niente si rompe. Passare da <code>2.5.0</code> a <code>3.0.0</code> dice: leggi questa voce prima di aggiornare. Changelog e numero di versione dovrebbero affermare la stessa cosa in due formati, e la maggior parte degli attriti tra i due emerge proprio quando non concordano, il che succede più spesso di quanto la specifica suggerirebbe.</p> <h2>Cosa promette davvero ogni numero in una versione?</h2> <p>Il <a href="https://semver.org/">semantic versioning</a> definisce tre numeri, <code>MAJOR.MINOR.PATCH</code>, ognuno con una regola rigida su cosa lo attiva. Un salto MAJOR significa un cambiamento incompatibile: qualcosa che un'integrazione corretta ed esistente potrebbe notare e per cui dovrebbe cambiare. Un salto MINOR significa nuova funzionalità compatibile all'indietro: niente di esistente si rompe, qualcosa di nuovo è disponibile. Un salto PATCH significa un fix compatibile all'indietro: il comportamento si avvicina a quanto documentato, e chi contava intenzionalmente sul vecchio comportamento non dovrebbe notare nulla.</p> <table> <thead> <tr> <th>Salto</th> <th>Significato</th> <th>La voce dovrebbe leggersi come</th> </tr> </thead> <tbody><tr> <td>MAJOR (<code>1.x.x</code> -> <code>2.0.0</code>)</td> <td>Un cambiamento incompatibile</td> <td>"Serve agire prima di aggiornare"</td> </tr> <tr> <td>MINOR (<code>1.2.x</code> -> <code>1.3.0</code>)</td> <td>Nuova capacità compatibile</td> <td>"Disponibile da ora, nient'altro cambia"</td> </tr> <tr> <td>PATCH (<code>1.2.3</code> -> <code>1.2.4</code>)</td> <td>Un fix compatibile</td> <td>"Ora si comporta come documentato"</td> </tr> </tbody></table> <p>La tabella è anche un test da eseguire al contrario: se una voce non si legge come la sua riga, o il numero di versione è sbagliato, o la voce sta sotto o sovra vendendo cosa è realmente successo.</p> <h2>Cosa conta come cambiamento incompatibile ai fini del versionamento?</h2> <p>Lo stesso test che decide se qualcosa appartiene a un changelog di API: se una chiamata corretta, scritta contro il vecchio comportamento e mai toccata da allora, potrebbe comportarsi in modo diverso a causa di questo cambiamento. <a href="https://changeloop.dev/blog/it/breaking-changes/">Cos'è un cambiamento incompatibile, e come rilasciarlo</a> copre la decisione per intero, inclusi i casi che sembrano incompatibili e non lo sono, e quelli che sembrano piccoli e non lo sono. In breve ai fini del versionamento: se la risposta è sì, il salto è MAJOR indipendentemente da quanto codice il cambiamento abbia toccato internamente. I numeri di versione seguono la conseguenza per chi chiama, non lo sforzo del team.</p> <h2>Come dovrebbe corrispondere una voce di changelog a un salto di versione?</h2> <p>Una voce, una categoria di salto, dichiarata subito. Il pattern della tabella continua direttamente: una voce incompatibile sta sotto la versione che l'ha introdotta, formulata prima come avviso e poi come descrizione. Una voce additiva sta sotto la sua versione MINOR, formulata come disponibilità. Un fix sta sotto la sua versione PATCH, formulato come correzione. Mescolare categorie in una voce, come infilare un cambiamento incompatibile nello stesso paragrafo di un fix non correlato, è il modo in cui chi legge perde proprio l'unica cosa che contava davvero.</p> <pre><code>## 3.0.0 (2026-09-07) ### Changed - **BREAKING:** `GET /reports` ora restituisce gli importi come interi nell'unità monetaria più piccola (centesimi) invece che come decimali. Aggiorna il codice che legge `amount` direttamente. ## 2.9.0 (2026-09-01) ### Added - I report ora si possono filtrare per `status`. ## 2.8.4 (2026-08-28) ### Fixed - `GET /reports?status=` restituiva una pagina vuota invece di un 400 per uno stato sconosciuto. </code></pre> <p>Letto dall'alto in basso, il numero di versione e l'etichetta di sezione dicono la stessa cosa due volte, ed è esattamente lo scopo: chi legge solo i titoli ottiene una lettura corretta del rischio prima di aprire una sola riga.</p> <h2>La regola dei cambiamenti incompatibili si applica allo stesso modo prima della 1.0.0?</h2> <p>No, ed è qui che nasce la maggior parte della confusione su "era davvero incompatibile". SemVer è esplicito nel dire che la versione maggiore zero, <code>0.y.z</code>, serve allo sviluppo iniziale: qualsiasi cosa può cambiare in qualsiasi momento, e l'API pubblica non dovrebbe essere considerata stabile. Un salto da <code>0.4.0</code> a <code>0.5.0</code> può portare un cambiamento incompatibile senza violare la specifica, perché la garanzia sulla versione maggiore parte solo una volta che un progetto pubblica <code>1.0.0</code>. Una voce di changelog deve comunque a chi legge la stessa onestà su cosa si è rotto; ciò che cambia è solo che il numero di versione in sé non è il segnale su cui affidarsi prima che arrivi la 1.0.0.</p> <h2>E se il tuo prodotto non rilascia versioni discrete?</h2> <p>La maggior parte dei prodotti SaaS distribuisce in continuo e non mostra mai un numero di versione a chi chiama, il che non elimina il bisogno di questa disciplina, solo il numero che normalmente la porterebbe. La voce di changelog deve fare tutto il lavoro da sola: dire chiaramente se un cambiamento è incompatibile, additivo o un fix, con le stesse tre parole che usa il semantic versioning, anche senza un campo versione a cui agganciarle. Alcuni team mantengono una versione puramente interna solo per ancorare le voci di changelog a qualcosa di collegabile, senza mai mostrarla direttamente a chi chiama.</p> <h2>Come si applica questo specificamente a un changelog di API?</h2> <p>In modo più rigido che quasi ovunque altrove, perché chi chiama un'API è codice, non persone che possono scrollare le spalle davanti a un cambiamento inaspettato. <a href="https://changeloop.dev/blog/it/api-changelog/">Changelog di API: cosa pubblicare e chi lo legge</a> copre la forma completa di quel documento; la disciplina di versionamento qui è ciò che mantiene oneste le sue sezioni breaking e additive. Un'API che offre più versioni contemporaneamente, come <code>v1</code> e <code>v2</code> servite in parallelo durante una finestra di migrazione, sta di fatto applicando il semantic versioning alla scala dell'intera interfaccia invece di un singolo pacchetto, e lo stesso vocabolario di tre parole si applica ancora a ogni voce.</p> <h2>Cosa dice Keep a Changelog sul versionamento?</h2> <p>Si lega direttamente per nome al semantic versioning e raccomanda lo stesso vocabolario di categorie usato in questo articolo: Added, Changed, Deprecated, Removed, Fixed, Security. <a href="https://changeloop.dev/blog/it/keep-a-changelog-implemented/">Keep a Changelog, in pratica</a> percorre come adottare quella specifica, inclusi i punti in cui i team tendono a deviare. La sovrapposizione non è un caso: entrambe le specifiche cercano di risolvere lo stesso problema da estremi opposti, una standardizza il numero di versione e l'altra la voce che lo spiega.</p> <h2>FAQ</h2> <p><strong>Ogni voce di changelog ha bisogno di un numero di versione?</strong> Se il prodotto rilascia versioni, sì, perché il numero permette a chi legge di saltare direttamente a "quanto mi riguarda" senza leggere prima la voce. Se il prodotto distribuisce in continuo senza campo versione, la formulazione della voce deve portare da sola quel segnale.</p> <p><strong>Qual è la differenza tra un salto MAJOR e una voce di cambiamento incompatibile?</strong> Dovrebbero essere lo stesso evento descritto in due modi. Il numero di versione è il segnale leggibile dalla macchina (gli strumenti di chi chiama possono reagirvi); la voce di changelog è la spiegazione leggibile dall'uomo di cosa è cambiato concretamente.</p> <p><strong>Una release PATCH può essere incompatibile?</strong> Per definizione non dovrebbe. Se ne è uscita una comunque, non modificate né ritaggate la versione pubblicata: la <a href="https://semver.org/#what-do-i-do-if-i-accidentally-release-a-backward-incompatible-change-as-a-minor-version">FAQ di SemVer</a> dice di rilasciare una nuova versione che ripristini la compatibilità, o una nuova MAJOR se l'incompatibilità resta, e di documentare la versione incriminata così che gli utenti sappiano di saltarla.</p> <p><strong>I cambiamenti puramente interni hanno bisogno di un salto di versione?</strong> No. Il semantic versioning segue l'interfaccia pubblica. Un refactoring senza effetto osservabile per chi chiama non ha bisogno né di un salto né di una voce di changelog, anche se è stato un lavoro di ingegneria significativo.</p> </article> <article> <h1>L'header sunset delle API, e quando inviarne uno</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p><code>Sunset</code> è un singolo header di risposta, definito nella <a href="https://www.rfc-editor.org/rfc/rfc8594">RFC 8594</a>, che dice a chi chiama quando una risorsa smetterà di rispondere. <a href="https://changeloop.dev/blog/it/api-deprecation/">Deprecazione API</a> copre l'intera timeline annuncio-promemoria-brownout-ritiro e gli avvisi che la accompagnano; questo articolo riguarda l'unico segnale leggibile da una macchina in quella timeline, cosa dice davvero, e l'unico caso in cui la RFC stessa dice di non inviarlo.</p> <h2>Cosa dice l'header Sunset, e cosa non dice?</h2> <p>Contiene una singola data HTTP, il momento in cui ci si aspetta che la risorsa smetta di rispondere:</p> <pre><code>Sunset: Sat, 31 Dec 2028 23:59:59 GMT </code></pre> <p>La RFC la definisce un suggerimento, non una garanzia: non promette che la risorsa continuerà a funzionare fino a quel timestamp, e non dice nulla su come apparirà un eventuale guasto in seguito. Chi chiama può ricevere un 4xx, un redirect, o nessuna risposta; l'header non fa distinzioni. Un timestamp già nel passato significa "adesso, o in qualsiasi momento", non un errore nel valore. Niente di tutto questo è imposto dal protocollo. Un client che non legge mai l'header si comporta esattamente come ha sempre fatto, e scopre che la risorsa non c'è più nello stesso modo in cui lo avrebbe comunque scoperto.</p> <h2>Quando dovreste inviarlo davvero?</h2> <p>Solo quando la risorsa sta davvero per smettere di rispondere, non quando è semplicemente non più la scelta consigliata. La RFC è esplicita nel dire che la deprecazione avviene in due fasi, e il campo header Sunset appartiene solo alla seconda: l'API resta pienamente operativa durante la prima fase, l'annuncio che una versione non è più preferita, e il campo header non si applica lì. Si applica quando la versione è effettivamente pianificata per smettere di rispondere.</p> <p>Questo corrisponde direttamente alla timeline di deprecazione: l'header <code>Deprecation</code> viene inviato fin dal primo giorno, al passo dell'annuncio; <code>Sunset</code> descrive la data in cui il vecchio comportamento smetterà davvero, che è la stessa data che <a href="https://changeloop.dev/blog/it/api-deprecation/">la timeline in quattro passi</a> chiama ritiro. Inviare <code>Sunset</code> il primo giorno non è sbagliato, dato che la data è già fissata a quel punto, ma inviarlo senza aver anche annunciato una deprecazione, o impostarlo per una versione che non avete ancora davvero deciso di ritirare, dice ai chiamanti qualcosa che voi stessi non avete ancora deciso.</p> <h2>Interagisce con la cache?</h2> <p>No, e la RFC lo dice direttamente: <code>Sunset</code> e la cache HTTP risolvono problemi non correlati e vanno lette come complementari, non sovrapposte. Gli header di cache dicono quando è sicuro riutilizzare una copia in cache; <code>Sunset</code> non dice nulla sullo stato attuale della risorsa, solo che la risorsa stessa smetterà di esistere. Una risposta può essere pienamente cacheabile fino al momento esatto in cui va in sunset. Non usate l'uno per approssimare l'altro, e non date per scontato che un <code>max-age</code> lungo annulli una data di sunset imminente, né il contrario.</p> <h2>Un solo header può mettere in sunset più di un endpoint?</h2> <p>L'header si applica alla risorsa che lo ha restituito, ma la RFC permette a un servizio di documentare un ambito più ampio: una data di sunset sulla risorsa principale di un'API può essere definita per indicare che sparisce l'intera API, non solo quell'unico URL. Il problema è che questo funziona solo per chi chiama e conosce già la vostra regola di ambito. Chi legge l'header alla lettera vede un sunset sulla singola risorsa richiesta e nient'altro, quindi un ambito più ampio deve essere scritto da qualche parte dove chi chiama possa trovarlo, non semplicemente sottinteso.</p> <h2>Cosa dovrebbe accompagnare l'header?</h2> <p>Un link a dove il ritiro viene spiegato. La RFC 8594 registra una propria relazione di link <code>sunset</code> esattamente per questo: puntare a una risorsa che descrive la policy di ritiro, la data imminente, o come migrare, separatamente dal semplice timestamp dell'header.</p> <pre><code>HTTP/1.1 200 OK Sunset: Sat, 31 Dec 2028 23:59:59 GMT Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Puntare quel link ai vostri <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> o a una pagina di migrazione dedicata trasforma un header che quasi nessun codice client ispeziona in qualcosa che una persona che va a cercare trova subito. Combinatelo con la relazione <code>successor-version</code> degli <a href="https://changeloop.dev/blog/it/api-deprecation/#which-headers-should-a-deprecated-endpoint-send">header di deprecazione</a> e chi chiama ottiene, dalla sola risposta, sia dove andare sia cosa sostituisce questa risorsa.</p> <h2>Come si presenta tutto questo, dall'inizio alla fine?</h2> <p>Supponiamo che <code>v1</code> sparisca il 1 marzo 2027. L'annuncio di deprecazione il primo giorno aggiunge <code>Deprecation</code> e <code>Link: rel="successor-version"</code> a ogni risposta <code>v1</code>, secondo <a href="https://changeloop.dev/blog/it/api-deprecation/">gli header di deprecazione</a>, ma rimanda <code>Sunset</code> finché la data di ritiro non è davvero fissata invece di essere un segnaposto. Una volta fissata, ogni risposta <code>v1</code> porta:</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/docs/sunset-policy>; rel="sunset" </code></pre> <p>Il gateway o il monitoraggio di chi chiama può segnalare in modo indipendente su entrambi gli header: <code>Deprecation</code> dice che esiste una versione più recente, <code>Sunset</code> dice che questa ha un orologio che scorre. Nessuno dei due header deve necessariamente cambiare prima del 1 marzo; ciò che cambia è la risposta stessa, nel giorno stesso, e durante eventuali finestre di brownout pianificate prima di allora.</p> <h2>Un brownout cambia cosa dice l'header?</h2> <p>Il valore dell'header non deve necessariamente spostarsi per un brownout pianificato: la data di sunset resta la data di sunset, che la risorsa fallisca in modo intermittente prima o no. Ciò che cambia è la risposta, non l'header. Pianificare brevi finestre di <code>410 Gone</code> nelle settimane prima della data annunciata, come descrive <a href="https://changeloop.dev/blog/it/api-deprecation/">Deprecazione API</a>, è ciò che trasforma il primo contatto di chi chiama con il guasto in una prova generale invece che nell'evento reale il giorno in cui arriva la data dell'header.</p> <h2>FAQ</h2> <p><strong>Client o strumenti HTTP reali leggono davvero l'header Sunset?</strong> Raramente, lato client. Il suo valore è soprattutto per chi gestisce l'infrastruttura tra voi e chi chiama: un API gateway o uno strumento di monitoraggio che configurate per osservare l'header può avvisare il vostro team, o quello di un partner, molto prima che il codice di chi chiama se ne accorga mai. Trattatelo come un segnale attorno a cui costruire strumenti, non uno che potete dare per scontato che l'altra parte abbia già.</p> <p><strong><code>Sunset</code> è la stessa cosa di <code>Cache-Control: max-age</code>?</strong> No. <code>max-age</code> riguarda per quanto tempo resta valida una copia in cache; <code>Sunset</code> riguarda quando la risorsa smette del tutto di esistere. Una risposta può avere un <code>max-age</code> breve e una data <code>Sunset</code> lontana anni, o il contrario, e nessuno dei due header vincola l'altro.</p> <p><strong>Posso inviare Sunset per un singolo campo che sparisce, non per l'intero endpoint?</strong> No, l'header ha come ambito la risorsa, cioè l'URL, non un campo dentro il corpo della risposta. Per un campo, un parametro o un valore enum che sparisce mentre l'endpoint stesso resta attivo, usate invece l'header <code>Deprecation</code> e una voce di changelog; <a href="https://changeloop.dev/blog/it/api-deprecation/">Deprecazione API</a> copre esattamente come annunciare quel tipo di cambiamento.</p> <p><strong>E se la data di sunset deve essere spostata?</strong> Aggiornate il valore dell'header e ditelo nella voce di changelog che l'aveva annunciata la prima volta; cambiare silenziosamente una data pubblicata è il modo in cui chi chiama decide che nessuna delle vostre date è reale. La RFC descrive il valore come un suggerimento proprio perché le date a volte si spostano, ma una data spostata senza spiegazione vi costa anche la prossima.</p> </article> <article> <h1>Changelog dei webhook: il breaking change non richiesto</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un changelog di API REST esiste perché un chiamante può scegliere di rifiutare una risposta che non capisce, o almeno registrare un errore abbastanza rumoroso perché qualcuno se ne accorga. Un destinatario di webhook raramente fa nessuna delle due cose. Riceve un POST, legge i campi che si aspetta, e se un campo si è spostato, ha cambiato tipo o è sparito, l'endpoint o crasha in silenzio dentro un job in background che nessuno controlla o, peggio, continua a funzionare con un valore sbagliato che non ha mai validato. <a href="https://changeloop.dev/blog/it/breaking-changes/">Cos'è un breaking change</a> copre la definizione generale; un payload di webhook ha bisogno della propria risposta, perché la modalità di fallimento è diversa da quella di un endpoint che qualcuno chiama di proposito.</p> <h2>Perché un cambiamento nel payload di un webhook si rompe diversamente da un cambiamento nella risposta di un'API?</h2> <p>Perché la direzione della richiesta è invertita. Chi chiama via REST avvia la chiamata e può aggiungere un header di versione, ritentare su un 4xx o leggere un avviso di deprecazione nella risposta. Un destinatario di webhook non ha avviato niente di tutto questo: il vostro server ha deciso di inviare, ha deciso quando, e ha deciso quale forma avrebbe avuto il corpo. L'unica leva del destinatario è la validazione che ha scritto quando l'integrazione è stata costruita, e la maggior parte delle integrazioni si costruiscono una volta, funzionano, e nessuno le rivede più finché non si rompono. Questa asimmetria è l'intero motivo per cui un cambiamento nel payload di un webhook merita più cautela dello stesso cambiamento in un corpo di risposta che un chiamante ha richiesto attivamente.</p> <h2>Cosa conta davvero come breaking change in un payload di webhook?</h2> <table> <thead> <tr> <th>Cambiamento</th> <th>Breaking per la maggior parte dei destinatari</th> </tr> </thead> <tbody><tr> <td>Aggiungere un nuovo campo</td> <td>No, se i destinatari ignorano i campi sconosciuti (verificate questa assunzione, non datela per scontata)</td> </tr> <tr> <td>Rimuovere un campo</td> <td>Sì, se qualcosa lo legge</td> </tr> <tr> <td>Rinominare un campo</td> <td>Sì, funzionalmente identico a rimuovere quello vecchio</td> </tr> <tr> <td>Cambiare il tipo di un campo (stringa a oggetto)</td> <td>Sì, quasi sempre</td> </tr> <tr> <td>Riordinare i campi nel corpo JSON</td> <td>No, per qualsiasi destinatario che analizza per chiave, che dovrebbero essere tutti</td> </tr> <tr> <td>Cambiare il nome o tipo dell'evento</td> <td>Sì, se i destinatari filtrano o instradano su di esso</td> </tr> </tbody></table> <p>La riga "aggiungere un campo è sicuro" è quella su cui i team fanno più affidamento e quella che vale di più verificare, non assumere. Un parser JSON permissivo ignora i campi sconosciuti per default, ma un destinatario che deserializza in uno schema rigido, diversi linguaggi tipizzati lo fanno senza configurazione extra, può rifiutare l'intero payload appena appare un campo inaspettato. Aggiungere un campo è sicuro per il vostro webhook solo se sapete come analizzano i destinatari, non perché JSON in sé sia permissivo.</p> <h2>Come si versiona un payload di webhook?</h2> <p>Più o meno come per una risposta API, con una differenza: il destinatario non invia mai una richiesta, quindi non può chiedere una versione, ed è il mittente a doverla dichiarare. Può stare nel corpo o in un header della richiesta di consegna stessa; le <a href="https://docs.github.com/en/webhooks/webhook-events-and-payloads">consegne di GitHub</a> portano <code>X-GitHub-Event</code> e <code>X-GitHub-Hook-ID</code>, e la <a href="https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md">specifica Standard Webhooks</a> mette i suoi metadati negli header <code>webhook-*</code>. Un campo di versione nel payload (<code>"payload_version": 2</code>) è l'opzione più economica e funziona quando i destinatari sono disposti a diramarsi su di esso. Un tipo di evento versionato (<code>invoice.updated</code> diventa <code>invoice.updated.v2</code> come evento distinto a cui un destinatario si iscrive volontariamente) richiede più lavoro da costruire ma significa che la forma vecchia continua ad arrivare a chi non ha mai migrato, il che conta di più qui che per un endpoint REST perché non potete chiamare ogni destinatario per dirgli di aggiornare. Un'impostazione per sottoscrizione, scelta alla registrazione dell'endpoint del webhook, anticipa la decisione invece di diramarsi a ogni consegna, ed è la scelta giusta quando avete già un record di sottoscrizione a cui attaccarla.</p> <pre><code>POST /endpoint-destinatario { "event": "invoice.updated", "payload_version": 2, "data": { "invoice_id": "inv_123", "status": "paid" } } </code></pre> <h2>Come fai anche solo a sapere chi sta ascoltando?</h2> <p>Peggio della versione equivalente di questo problema in un changelog di API, perché un webhook non ha un log delle richieste in entrata dalla vostra parte che nomini il chiamante; avete solo il vostro log di consegna in uscita, che vi dice che un endpoint ha ricevuto un 200, non cosa ne ha fatto del corpo. Tracciate almeno due cose: ogni endpoint registrato con una responsabile, la stessa disciplina che <a href="https://changeloop.dev/blog/it/internal-api-changelog/">i changelog di API interne</a> raccomandano per i consumatori interni, e il vostro tasso di fallimento della consegna per endpoint dopo un cambiamento di payload. Un picco di risposte 4xx o 5xx da un endpoint subito dopo un cambiamento è la cosa più vicina a uno stack trace che otterrete, e spesso è l'unico segnale che un destinatario si è rotto, perché il team che lo gestisce potrebbe non accorgersene per giorni.</p> <h2>Un changelog dei webhook dovrebbe essere separato dal changelog delle API?</h2> <p>Una sezione separata sulla stessa pagina, non una pubblicazione separata. <a href="https://changeloop.dev/blog/it/api-changelog/">Un changelog di API</a> stabilisce già chi lo legge e come ci si iscrive; un cambiamento nel payload di un webhook appartiene allo stesso feed, etichettato con chiarezza sufficiente perché una sviluppatrice lato destinatario che cerca "questo influisce sulla mia integrazione" possa filtrarlo, perché una consumatrice di webhook spesso non ha altro motivo per controllare un changelog generale di API e lo troverà solo se qualcuno la indirizza lì direttamente.</p> <h2>Come dovrebbe essere una finestra di deprecazione ragionevole per un payload di webhook?</h2> <p>Più lunga della deprecazione REST equivalente, perché la migrazione lato destinatario di solito significa che un secondo team, con cui magari non avete un contatto diretto, deve accorgersene, pianificarla e rilasciarla senza una propria urgenza. Un mese è un minimo ragionevole per un campo che il destinatario sta plausibilmente ancora analizzando con una libreria permissiva; tre mesi o più sono più sicuri per una rimozione di campo che uno schema rigido rifiuterebbe del tutto. Inviate la forma vecchia e quella nuova insieme durante la finestra quando fattibile (il vecchio campo <code>status</code> e il suo sostituto della versione 2 nello stesso payload), perché un destinatario che legge il campo vecchio continua a funzionare senza toccare il codice, e uno che ha già migrato ignora semplicemente il campo di cui non ha più bisogno.</p> <h2>FAQ</h2> <p><strong>I consumatori di webhook devono confermare un cambiamento di payload prima che venga rilasciato?</strong> Non esiste un meccanismo di conferma di default, ed è proprio per questo che la finestra di deprecazione conta di più qui che per un'API REST: nessuno conferma di essere pronto, quindi la finestra deve essere abbastanza lunga da far migrare la maggior parte dei destinatari secondo i propri tempi prima che la forma vecchia scompaia.</p> <p><strong>È mai sicuro aggiungere campi sconosciuti senza preavviso?</strong> Solo dopo aver verificato, non assunto, che i vostri destinatari analizzano in modo permissivo. Una voce di changelog costa poco e toglie l'incertezza; aggiungere campi in silenzio assumendo che "i parser JSON ignorano gli extra" rompe qualsiasi destinatario con deserializzazione rigida.</p> <p><strong>Qual è il modo più veloce per rilevare un destinatario di webhook rotto dopo un cambiamento di payload?</strong> Un tasso di fallimento della consegna per endpoint, osservato nelle ore subito dopo il cambiamento. Non vi dirà cosa si è rotto, solo che qualcosa si è rotto, ma è il segnale più precoce e spesso l'unico che otterrete.</p> <p><strong>La logica di retry aiuta i destinatari a sopravvivere a un cambiamento di payload?</strong> No. Un retry rinvia lo stesso nuovo payload; non torna a una forma che il destinatario può analizzare. Un cambiamento di payload rompe un destinatario alla prima consegna e a ogni retry successivo in modo identico.</p> </article> <article> <h1>Changelog: cos'è, con un esempio di voce</h1> <p>Mon, 07 Sep 2026 00:00:00 GMT</p> <p>Un changelog è il registro datato di ciò che è cambiato in un prodotto, scritto per le persone coinvolte dal cambiamento, non per il team che lo ha rilasciato. Ogni voce nomina un cambiamento, dice quando è entrato in vigore e dice cosa deve fare chi legge, che nella maggior parte dei casi è niente. Proprio questo separa un changelog da un log dei commit: un log dei commit è un registro per chi ha scritto il codice, un changelog è un registro per chi lo usa.</p> <h2>Cos'è un changelog, esattamente?</h2> <p>Un elenco di voci datate, dalla più recente, ognuna descrive un singolo cambiamento in termini che chi legge può verificare. Non cosa ha costruito il team, ma cosa è diverso ora. "Refactoring del servizio di fatturazione" è un messaggio di commit. "Le fatture ora mostrano l'imposta come riga separata" è una voce di changelog, perché dice a chi legge qualcosa che può controllare sul proprio account.</p> <p>Il formato è antico e volutamente semplice: un titolo per release o per giorno, un elenco breve sotto, a volte un'etichetta di categoria. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> è la specifica più citata per questa forma, ed esiste perché la maggior parte dei progetti che salta una specifica finisce per riversare la cronologia dei commit al suo posto, che risponde a una domanda diversa da quella con cui è arrivato chi legge.</p> <table> <thead> <tr> <th>Documento</th> <th>Scritto per</th> <th>Risponde a</th> </tr> </thead> <tbody><tr> <td>Changelog</td> <td>Chiunque usi il prodotto</td> <td>Cosa è cambiato, e quando?</td> </tr> <tr> <td>Log dei commit</td> <td>Il team che ha scritto il codice</td> <td>Cosa è stato fatto, in che ordine?</td> </tr> <tr> <td>Note di rilascio</td> <td>Utenti che decidono se aggiornare</td> <td>Cosa posso fare ora che non potevo?</td> </tr> <tr> <td>Note di patch</td> <td>Giocatori o utenti di un fix specifico</td> <td>Cosa ha risolto proprio questa release?</td> </tr> <tr> <td>Roadmap</td> <td>Chiunque si chieda cosa arriva dopo</td> <td>Cosa è pianificato, e a che punto è?</td> </tr> </tbody></table> <p>I cinque si sovrappongono nella pratica, ma non sono lo stesso documento, e la differenza sta in chi lo tiene in mano quando lo legge. Un changelog è quello costruito per essere cercato e collegato in seguito, per cui le sue voci hanno più bisogno di date e URL stabili degli altri.</p> <h2>Cosa contiene davvero una voce di changelog?</h2> <p>Quattro cose, in quest'ordine: cosa è cambiato, espresso nei termini in cui l'utente o il chiamante lo noterebbe; quando è entrato in vigore; a quale categoria appartiene (added, fixed, changed, removed sono le quattro comuni); e, quando conta, cosa deve fare chi legge al riguardo. Un link per approfondire è benvenuto. Un paragrafo di giustificazione interna no, perché chi legge non ha chiesto perché, ha chiesto cosa.</p> <pre><code>## 2026-09-07 ### Added - Le fatture ora mostrano l'imposta come riga separata, nella valuta dell'account del cliente. ### Fixed - Esportare un report come CSV non elimina più l'ultima riga quando il report supera le 10.000 righe. </code></pre> <p>Questa forma scala da un aggiornamento di due righe a cento voci in una release senza cambiare struttura, ed è il vero test se un formato funziona: si legge allo stesso modo in una settimana intensa e in una tranquilla.</p> <h2>Chi scrive un changelog, e quando?</h2> <p>Chi ha fatto il cambiamento, nel momento in cui viene rilasciato, non una redattrice tecnica che lo ricostruisce dai ticket una settimana dopo. Chi ha toccato il codice sa cosa è cambiato davvero per l'utente; un riassunto scritto in seguito tende a descrivere il ticket invece di ciò che è stato effettivamente rilasciato, ed è di solito più ampio o più stretto dell'effettivo. Alcuni team aggiungono un passaggio di revisione prima che una voce diventi pubblica, soprattutto per intercettare linguaggio interno che si è infilato, e quella revisione dovrebbe essere abbastanza rapida da far uscire la voce lo stesso giorno.</p> <h2>Dove dovrebbe vivere un changelog?</h2> <p>Sulla propria pagina, con un URL stabile, distribuito come feed. Sepolto in un menu delle impostazioni o in un tag di release su un host di codice, raggiunge solo chi già sapeva dove guardare. Una pagina pubblica si può collegare da un ticket di supporto, citare in una recensione o sottoscrivere. Il feed conta quanto la pagina: chi controlla il changelog di un prodotto una volta al mese è raro, chi lo sottoscrive no, e solo il feed serve il secondo tipo.</p> <h2>In cosa differisce dalle note di rilascio?</h2> <p>Vengono confusi costantemente, e sono abbastanza diversi che unirli produce un documento che non serve bene nessuna delle due lettrici. <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">Changelog vs note di rilascio</a> percorre la distinzione per intero; in breve, un changelog è il registro completo e cronologico, e le note di rilascio sono un sottoinsieme curato, scritto perché un aggiornamento suoni degno di essere avuto. Un prodotto di solito ha bisogno di entrambi, rivolti a momenti diversi della giornata di chi legge.</p> <h2>Cosa rende un changelog degno di essere letto?</h2> <p>Specificità e onestà sulla propria portata. "Vari bugfix" è la frase che insegna a chi legge a smettere di aprire la pagina, perché non promette nulla che possa verificare. Una voce che nomina il comportamento esatto cambiato, anche per un fix piccolo, è quella che tiene viva un'iscrizione. Questa disciplina vale anche per le omissioni: un changelog che annuncia solo successi e mai un fix per qualcosa che era rotto si legge come marketing travestito da changelog, e chi legge se ne accorge.</p> <p>Conta anche la disciplina di versionamento. <a href="https://changeloop.dev/blog/it/semantic-versioning-changelog/">Semantic versioning e il tuo changelog</a> spiega come numero di versione e voce dovrebbero corrispondere, così chi scorre la cronologia delle versioni riceve lo stesso segnale due volte invece di due segnali diversi.</p> <h2>Come vengono generati i changelog?</h2> <p>In due modi, e la maggior parte delle configurazioni reali è un mix. La generazione automatizzata legge i messaggi di commit, di solito in formato <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, e li trasforma in voci senza che nessuno tocchi l'output; <a href="https://changeloop.dev/blog/it/conventional-commits-changelog/">dai conventional commits al changelog</a> copre quella pipeline. La generazione curata significa che qualcuno scrive o modifica ogni voce a mano. L'output automatizzato è più veloce e non perde mai una pull request unita, ma eredita ogni messaggio di commit vago parola per parola, per cui la maggior parte dei team che automatizza mantiene comunque un passaggio di revisione leggero prima di pubblicare invece di mostrare l'output grezzo.</p> <h2>FAQ</h2> <p><strong>Ogni prodotto ha bisogno di un changelog?</strong> Qualsiasi prodotto con utenti coinvolti dal cambiamento ne ha bisogno, che sia un'app SaaS, uno strumento interno o un'API pubblica. La forma si adatta (un changelog di API si legge diverso da quello di un'app consumer), il bisogno no.</p> <p><strong>Cos'è un changelog in termini di software?</strong> La stessa definizione di sopra: un elenco datato e cronologico di ciò che è cambiato nel software, scritto per chi lo usa, non per chi lo ha costruito.</p> <p><strong>Un changelog può essere generato automaticamente dai commit?</strong> Sì, e molti team fanno esattamente questo, di solito da messaggi in formato Conventional Commits. Il compromesso è che una voce generata è chiara solo quanto il messaggio di commit da cui proviene, per cui un passaggio di revisione prima della pubblicazione intercetta quelle da riformulare.</p> <p><strong>Un changelog è lo stesso di una cronologia delle versioni?</strong> Abbastanza simile da usare i termini in modo intercambiabile. Una cronologia delle versioni a volte è solo un elenco di numeri e date senza descrizione; un changelog include sempre cosa è cambiato.</p> </article> <article> <h1>Changelog di API: cosa pubblicare e chi lo legge</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Un changelog di API è il registro datato di ogni cambiamento che un chiamante potrebbe notare, scritto per chi integra con l'API, non per il team che la rilascia. Questo pubblico lo rende un documento diverso da un changelog di prodotto: chi legge sta decidendo se il proprio codice funzionerà ancora il mese prossimo. La maggior parte fallisce nello stesso modo, essendo una copia filtrata di un feed interno di release, così un campo rimosso finisce accanto a una correzione di testo con lo stesso peso, e nessuno dei due viene letto.</p> <h2>Cos'è un changelog di API?</h2> <p>È il registro pubblico e datato dei cambiamenti a un'interfaccia contro cui altre persone hanno scritto codice. Il test utile per stabilire se qualcosa vi appartiene non ha nulla a che fare con quanto fosse grande il cambiamento internamente. Chiede se un chiamante corretto, scritto l'anno scorso e mai toccato da allora, potrebbe comportarsi diversamente a causa sua. Questo test ammette alcuni cambiamenti molto piccoli ed esclude alcuni molto grandi.</p> <p>Tutto quello che segue presuppone che chi chiama sia fuori dall'azienda e sostanzialmente irraggiungibile se non tramite questo documento. Quando chi chiama è un altro team della stessa azienda, il calcolo cambia abbastanza da richiedere un trattamento proprio; <a href="https://changeloop.dev/blog/it/internal-api-changelog/">changelog di API interna</a> copre cosa serve invece a quel pubblico.</p> <table> <thead> <tr> <th>Documento</th> <th>Pubblico</th> <th>Risponde a</th> </tr> </thead> <tbody><tr> <td>Changelog di API</td> <td>Sviluppatori che chiamano l'API</td> <td>La mia integrazione funziona ancora?</td> </tr> <tr> <td>Note di rilascio</td> <td>Utenti del prodotto</td> <td>Cosa posso fare ora che prima non potevo?</td> </tr> <tr> <td>Avviso di deprecazione</td> <td>Chiamanti di una cosa specifica</td> <td>Quando smette di funzionare?</td> </tr> <tr> <td>Pagina di stato</td> <td>Chiunque sia colpito ora</td> <td>È giù in questo momento?</td> </tr> <tr> <td>Guida alla migrazione</td> <td>Chiamanti in fase di aggiornamento</td> <td>Come passo da A a B?</td> </tr> </tbody></table> <p><a href="https://changeloop.dev/blog/it/api-migration-guide/">Come scrivere una guida di migrazione per API</a> copre per intero quest'ultimo documento; in breve è ciò a cui una voce di cambiamento incompatibile dovrebbe rimandare invece di provare a sostituirlo.</p> <p>I cinque sono documenti separati con cicli di vita separati. Un avviso di deprecazione è una promessa con una data, e appartiene anche al changelog, ma una voce di changelog si scrive una volta sola mentre una deprecazione si segue fino al suo sunset. Confonderli è il motivo per cui i sunset vengono persi.</p> <h2>Cosa appartiene a una singola voce?</h2> <p>Sei cose, e le prime tre sono quelle che di solito mancano. Il cambiamento, espresso in termini di richiesta o risposta piuttosto che del componente interno. Se rompe un chiamante corretto. Cosa deve fare il chiamante, incluso "niente". La data in cui è entrato in vigore. La versione o le versioni coinvolte. Un link alla guida di migrazione, quando esiste.</p> <p>Una voce che dice "migliorato l'endpoint account" fallisce su tutte e sei. Una voce che dice "il campo <code>accounts.type</code> ora restituisce <code>individual</code> dove prima restituiva <code>personal</code>; i valori esistenti restano invariati per gli account creati prima del 2 settembre; nessuna azione richiesta a meno che tu non confronti la stringa" risponde a tutte e sei in una frase.</p> <p>Categorizzate le voci per conseguenza, non per reparto. Tre etichette portano quasi tutto il valore: breaking, additive e fixed. <a href="https://semver.org/">Semantic Versioning</a> definisce già le prime due con precisione, e prendere in prestito le sue definizioni invece di inventarne di locali significa che chi conosce semver conosce le vostre etichette. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> ne offre un set più lungo se lo volete, e la sua regola centrale vale qui più che altrove: il log è per gli esseri umani, e un dump di titoli di commit non lo è.</p> <h2>In cosa un changelog di API differisce dalle note di rilascio?</h2> <p>Le note di rilascio descrivono cosa può fare ora il prodotto. Un changelog di API descrive qual è ora il contratto. Lo stesso lavoro rilasciato produce spesso una voce in entrambi, formulata in modo diverso, perché i pubblici hanno bisogno di cose diverse: un nuovo formato di esportazione è una funzione per un utente e un nuovo valore enum per un chiamante che dipende da quel campo.</p> <p>La conseguenza pratica è che i due non possono essere lo stesso feed con stile diverso. Un chiamante che si iscrive a tutto quello che rilasciate finirà per disiscriversi, e allora perderà il breaking change. Se pubblicate un feed, filtratelo; se ne pubblicate due, rendete quello API più stretto e non lasciateci mai entrare una voce di marketing. Confrontiamo entrambe le forme fianco a fianco in <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">changelog vs note di rilascio</a>.</p> <h2>Dove dovrebbe vivere un changelog di API?</h2> <p>Accanto alla documentazione di riferimento, su una URL stabile, con ogni voce indirizzabile singolarmente tramite un frammento o un proprio percorso. I chiamanti collegano le voci nelle revisioni degli incidenti e nei ticket interni, e una voce che non si può collegare finisce incollata come screenshot al suo posto.</p> <p>Pubblicatelo anche come output leggibile dalla macchina, oltre che come pagina. Un feed JSON che segue la <a href="https://www.jsonfeed.org/version/1.1/">specifica JSON Feed</a> o un <a href="https://www.rssboard.org/rss-specification">feed RSS</a> non costa nulla una volta che le voci sono dati strutturati, ed è ciò che permette a un cliente di inserire i vostri cambiamenti nel proprio processo di release. Questo decide anche se qualcuno ci costruisce sopra. GitHub documenta le sue <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versioni della REST API</a> accanto al riferimento per lo stesso motivo: la politica delle versioni fa parte dell'interfaccia.</p> <h2>Come si presenta una buona voce nella pratica?</h2> <p>Tre voci della stessa settimana, nella forma descritta sopra:</p> <pre><code>2026-09-02 Breaking v2 `POST /invoices` ora rifiuta una `currency` che non corrisponde alla valuta dell'account del cliente, restituendo 422 invece di convertire silenziosamente. I chiamanti che facevano affidamento sulla conversione devono inviare la valuta dell'account. Riguarda solo v2; v1 resta invariata fino al sunset del 2027-01-15. 2026-09-02 Additive v1, v2 `Invoice` guadagna un timestamp `settled_at`, null finché la fattura non viene saldata. Nessuna azione richiesta. I client che rifiutano campi sconosciuti dovrebbero essere aggiornati. 2026-08-31 Fixed v2 `GET /invoices?status=` restituiva una pagina vuota invece di un 400 per uno stato sconosciuto. Ora restituisce 400 con i valori accettati. I chiamanti con un errore di battitura prima non vedevano risultati, ora vedono un errore. </code></pre> <p>La terza è il tipo più spesso omesso, perché internamente è una correzione di bug. Per un chiamante che ha costruito un retry intorno a quella pagina vuota, è un cambiamento di comportamento, e la voce è ciò che evita il ticket di supporto. L'etichetta dice fixed e il corpo dice cosa un chiamante potrebbe notare, che è la distinzione che mantiene onesto il log senza gonfiare ogni correzione a breaking change.</p> <h2>Come si iscrivono i chiamanti?</h2> <p>Dategli più di un canale, perché hanno lavori diversi. Un feed per lo sviluppatore che vuole tutto. Email per chi vuole solo i breaking change. Header di risposta per il codice stesso, l'unico iscritto che non dimentica mai di controllare: l'<a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code> definito in RFC 8594</a> mette la data di ritiro nella risposta, dove una libreria client può registrarla.</p> <p>Il canale che la maggior parte dei team salta è quello diretto. Se un chiamante ha usato la scorsa settimana il campo che state cambiando, sapete chi è, e una email a quegli account vale più di qualsiasi quantità di broadcast. È la stessa disciplina del <a href="https://changeloop.dev/blog/it/customer-feedback-loop/">chiudere il ciclo di feedback del cliente</a>, applicata a un cambiamento che nessuno ha richiesto: le persone coinvolte vengono avvisate individualmente, e a tutti gli altri arriva il feed. Un webhook è un quarto canale con una propria modalità di fallimento da conoscere prima di farci affidamento: <a href="https://changeloop.dev/blog/it/webhook-changelog/">i changelog dei webhook</a> copre perché un cambiamento di payload lì si rompe in silenzio, senza chiamante che possa rifiutare la nuova forma.</p> <h2>Come si scrive una voce per un breaking change?</h2> <p>Iniziate con la rottura, non con il motivo. Un chiamante che scorre dieci voci deve sapere nella prima frase se questa gli costerà lavoro. Poi la data, le versioni coinvolte, la migrazione, e la scadenza se il vecchio comportamento sta per sparire invece di cambiare.</p> <p>Mettete lo stesso contenuto nell'avviso di deprecazione, nell'header di risposta e nell'email diretta, formulato in modo coerente, e date a tutti e quattro la stessa data. La divergenza tra loro è l'errore che trasforma un cambiamento pianificato in un incidente, perché il chiamante che ne ha letto solo uno agisce sulla data sbagliata. <a href="https://changeloop.dev/blog/it/breaking-changes/">Cos'è un breaking change</a> copre la decisione in sé, e <a href="https://changeloop.dev/blog/it/api-deprecation/">come deprecare un'API</a> copre il calendario che segue.</p> <p>In changeloop, un cambiamento di API diventa una voce quando la pull request viene fusa, una persona modifica e approva la bozza, e la voce viene pubblicata su <a href="https://changeloop.dev/docs">feed e widget</a> nello stesso momento in cui un chiamante il cui feedback dal widget è diventato l'issue GitHub chiusa dalla pull request viene avvisato su quell'issue. Il passo di revisione è quello che conta qui: un changelog di API è un documento contrattuale, e nessuna bozza dovrebbe raggiungere un chiamante senza che una persona l'abbia letta.</p> <h2>FAQ</h2> <p><strong>Ogni cambiamento di API ha bisogno di una voce nel changelog?</strong> Ogni cambiamento che un chiamante corretto potrebbe notare sì, inclusi quelli che considerate interni. I cambiamenti senza effetto osservabile sulla richiesta o sulla risposta no, e aggiungerli allena i lettori a scorrere senza leggere.</p> <p><strong>Il changelog di API dovrebbe vivere nei docs o sul sito di marketing?</strong> Nei docs, accanto al riferimento. Chi legge di solito è già lì, e un changelog sul sito di marketing tende ad acquisire un pubblico per cui non è stato scritto.</p> <p><strong>Fino a quando dovrebbe risalire?</strong> Indefinitamente. Le voci vengono citate anni dopo nelle revisioni degli incidenti, e un log troncato rompe quei link. Paginare invece di potare.</p> <p><strong>Serve un changelog separato per ogni versione di API?</strong> No, un unico log con un campo versione per voce è più facile da leggere e da cercare. Filtrare per versione è una funzione della pagina, non un motivo per dividere il documento.</p> </article> <article> <h1>Come costruire una pagina di changelog che si segue</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>Una pagina di changelog vale la pena costruirla quando qualcuno ci tornerebbe. È un'asticella più alta che averne semplicemente una, ed è l'asticella su cui la maggior parte fallisce: una pagina che esiste, è collegata nel footer, si aggiorna a raffiche e non la visita nessuno tranne durante un incidente. Le decisioni che separano le due si prendono prima di scrivere qualsiasi cosa, e riguardano soprattutto dove vive la pagina e cos'altro viene generato dallo stesso contenuto.</p> <h2>Cos'è una pagina di changelog?</h2> <p>È l'elenco pubblico e datato di cosa è cambiato in un prodotto, su una URL che vi appartiene. È una di cinque superfici su cui possono apparire le stesse voci, e la domanda utile non è quale scegliere ma quale sia canonica e quali vengano generate a partire da essa.</p> <table> <thead> <tr> <th>Superficie</th> <th>Meglio per</th> <th>Costo</th> </tr> </thead> <tbody><tr> <td>Pagina ospitata</td> <td>Ricerca, collegamenti, il registro lungo</td> <td>Una URL e un template</td> </tr> <tr> <td>Widget in-app</td> <td>Raggiungere utenti che non visitano mai la pagina</td> <td>Un embed, e moderazione</td> </tr> <tr> <td>Sezione docs</td> <td>Pubblico API e sviluppatori</td> <td>Tenerlo accanto al riferimento</td> </tr> <tr> <td>Feed JSON</td> <td>Clienti che costruiscono sui vostri cambiamenti</td> <td>Struttura che avete già</td> </tr> <tr> <td>Feed RSS</td> <td>Sviluppatori che si iscrivono una volta</td> <td>Quasi niente</td> </tr> </tbody></table> <p>Scegliete una fonte canonica, pubblicate una volta, e generate il resto. I team che mantengono pagina e widget separatamente a mano finiscono con due testi che non concordano, e la discrepanza la scopre un cliente.</p> <h2>Dove dovrebbe vivere una pagina di changelog?</h2> <p>Sul vostro dominio, su un percorso stabile, con ogni voce indirizzabile singolarmente. Le tre collocazioni comuni sono un percorso sul sito principale, un sottodominio, e una sezione della documentazione. Un percorso sul sito principale è la scelta predefinita contro cui argomentare, non a favore: eredita l'autorità del sito, non serve un certificato o DNS extra, e mantiene la pagina nella stessa navigazione di tutto il resto.</p> <p>Un sottodominio è la risposta giusta quando la pagina è servita da un sistema diverso dal sito di marketing e altrimenti fareste proxy. Il costo è che accumula autorità separatamente. Mettere il changelog nei docs è giusto quando il pubblico è formato da sviluppatori, per la ragione trattata in <a href="https://changeloop.dev/blog/it/api-changelog/">changelog di API</a>: chi legge di solito è già lì.</p> <p>Più della scelta conta che le voci siano collegabili singolarmente. Le persone collegano le voci nelle revisioni degli incidenti e nei ticket interni, e una voce che si può collegare solo come "il changelog, scorri giù" finisce incollata come screenshot al suo posto.</p> <h2>Cosa serve a una pagina di changelog?</h2> <p>Cinque cose, e sulle prime due falliscono la maggior parte delle pagine. Una voce datata per cambiamento, la più recente per prima. Una categoria o etichetta per voce, per poter scorrere in cerca del tipo che interessa. Un permalink per voce. Una via di iscrizione. Una ricerca o filtro oltre le circa cinquanta voci.</p> <p>Tutto il resto è opzionale. Gli screenshot aiutano e costano manutenzione. I nomi degli autori costruiscono fiducia in alcuni prodotti e rumore in altri. I numeri di versione contano per i chiamanti di un'API e per quasi nessun altro. <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> è una scelta predefinita ragionevole per le etichette se non avete motivo di inventarne di vostre, e la sua regola centrale è quella da tenere anche se scartate il resto: il log è per gli esseri umani.</p> <p>Raggruppate per data invece che per release quando il vostro prodotto rilascia continuamente. Un lettore che scandaglia "questo era prima o dopo il nostro incidente del nove" cerca una data, e una pagina organizzata per numero di versione lo costringe a fare i conti.</p> <h2>Pagina o widget in-app?</h2> <p>Entrambi, da un'unica fonte. La pagina è dove vivono ricerca, link e il registro lungo. Il widget è come raggiungete la maggioranza degli utenti che non visiterà mai la pagina, e funziona perché appare nel prodotto che stanno già usando.</p> <p>Il fallimento del widget è l'interruzione. Un badge che chiede attenzione per ogni voce viene scartato in modo permanente entro una settimana, il che vi costa il canale per la voce che contava davvero. Contate i non letti dall'ultima volta che il lettore ha guardato, seminate il contatore in silenzio alla prima visita così nessuno viene accolto da un badge di un anno di storia, e lasciate che sia il lettore ad aprirlo invece di aprirlo per lui.</p> <h2>Come si rende leggibile dalla macchina una pagina di changelog?</h2> <p>Pubblicate le stesse voci come feed. Un <a href="https://www.jsonfeed.org/version/1.1/">feed JSON</a> è l'opzione a minore attrito per chiunque lo consumi via codice, e un <a href="https://www.rssboard.org/rss-specification">feed RSS</a> è ciò che si aspetta uno sviluppatore che si iscrive in un reader. Entrambi costano poco una volta che le voci sono dati strutturati invece di HTML scritto a mano, il che è l'argomento reale per mantenere strutturata la copia canonica.</p> <p>Marcate anche la pagina. Le voci sono opere con data e titolo, e <a href="https://schema.org/CreativeWork">schema.org</a> fornisce il vocabolario. Vale la pena per lo stesso motivo dei permalink: rende la pagina utilizzabile da cose che non sono un browser, incluso il processo di release di un cliente. Niente di tutto questo funziona se le voci sottostanti non sono mai state dati strutturati fin dall'inizio; <a href="https://changeloop.dev/blog/it/changelog-file-formats/">formati file del changelog</a> copre cosa costa ciascuno tra Markdown, JSON e YAML come fonte di verità da cui questo feed e questo markup vengono davvero generati.</p> <h2>Una pagina di changelog aiuta la SEO?</h2> <p>Indirettamente e lentamente. Le voci singole raramente posizionano, perché non puntano a nessuna query che qualcuno digita. La pagina si guadagna il suo posto tramite i link: le voci vengono citate in risposte di supporto, forum e analisi degli incidenti, e quei link si accumulano su una URL che vi appartiene. Una pagina aggiornata ogni settimana per due anni è anche un segnale di freschezza credibile per il prodotto a cui appartiene.</p> <p>Ciò che non funziona è trattare le voci come content marketing. Una voce gonfiata a tre paragrafi per allungarla è peggiore nel suo lavoro reale, cioè dire a un lettore in una frase se qualcosa che usa è cambiato. Se volete che il changelog sostenga la ricerca, mettete lo sforzo nei permalink, nel feed e nei link interni verso di esso, e lasciate le voci brevi. La nostra pagina di <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> raccoglie pagine che colgono questo equilibrio.</p> <h2>Come si iscrive la gente?</h2> <p>Dategli le vie che già usano: un feed RSS o JSON per gli sviluppatori, email per chi vuole sentire solo le cose importanti, e il widget in-app per tutti quelli che non faranno mai né l'uno né l'altro. Chiedete cosa vogliono sentire invece di darlo per scontato, perché un lettore che vuole breaking change e riceve correzioni di testo si disiscrive da entrambi.</p> <p>La via da aggiungere per ultima è quella che chiude il ciclo. Quando una voce risolve qualcosa che una persona specifica ha chiesto, ditelo direttamente invece di sperare che legga la pagina. In changeloop la voce viene pubblicata in una sola volta su <a href="https://changeloop.dev/docs">pagina, feed e widget</a>, e una persona il cui feedback dal widget è diventato l'issue GitHub chiusa dalla pull request viene avvisata su quell'issue con un link alla voce, e vede la voce nel widget. Il meccanismo è lo stesso di qualsiasi iscrizione; la differenza è che chi riceve ha già chiesto. È l'argomento sviluppato in <a href="https://changeloop.dev/blog/it/customer-feedback-loop/">chiudere il ciclo di feedback dal changelog</a>.</p> <h2>FAQ</h2> <p><strong>La pagina di changelog dovrebbe stare su un sottodominio o un percorso?</strong> Un percorso sul sito principale per default, perché eredita l'autorità del sito e non serve infrastruttura extra. Un sottodominio si giustifica quando un sistema diverso serve la pagina.</p> <p><strong>Quante voci dovrebbe mostrare la pagina alla volta?</strong> Abbastanza da riempire uno schermo e non di più, con paginazione dopo. Caricare due anni di storia in un documento è lento e rende più difficile trovare la voce più recente.</p> <p><strong>Le voci vecchie andrebbero mai cancellate?</strong> No. Vengono citate da fuori del vostro sito e i link si rompono. Correggete una voce sul posto con una nota, e mantenete viva la URL.</p> <p><strong>Ogni cambiamento deve apparire sulla pagina?</strong> Solo quelli che un utente potrebbe notare. Una pagina che registra refactoring interni allena i lettori a scorrere senza leggere, e una pagina scorsa senza leggere fallisce il giorno in cui porta qualcosa di urgente.</p> </article> <article> <h1>Il template email di aggiornamento prodotto che si legge</h1> <p>Wed, 02 Sep 2026 00:00:00 GMT</p> <p>L'email di aggiornamento prodotto che si legge è quella inviata a qualcuno che ha chiesto esattamente ciò che annuncia. Tutto il resto compete con il resto della casella di posta per interesse, una gara che un annuncio di release perde la maggior parte delle settimane. Questo unico fatto dovrebbe decidere la forma dell'email prima di qualsiasi formulazione: chi la riceve, e cosa ha fatto quella persona per finire nella lista.</p> <h2>Cos'è un'email di aggiornamento prodotto?</h2> <p>È un messaggio che dice agli utenti esistenti cosa è cambiato in un prodotto che già usano. Ci sono quattro tipi distinti, e trattarli come un'unica lista è il motivo per cui i tassi di apertura decadono. Ognuno ha un trigger diverso, un pubblico diverso e una frequenza accettabile diversa.</p> <table> <thead> <tr> <th>Tipo</th> <th>Trigger</th> <th>Pubblico</th> <th>Frequenza</th> </tr> </thead> <tbody><tr> <td>Notifica mirata</td> <td>La richiesta specifica di qualcuno è stata rilasciata</td> <td>Una persona</td> <td>Ogni volta che succede</td> </tr> <tr> <td>Avviso breaking change</td> <td>Un cambiamento che costa lavoro al lettore</td> <td>Solo account coinvolti</td> <td>Ogni volta che succede</td> </tr> <tr> <td>Digest</td> <td>Il passare del tempo</td> <td>Utenti opt-in</td> <td>Al massimo mensile</td> </tr> <tr> <td>Annuncio di lancio</td> <td>Un lancio che vale un'interruzione</td> <td>Segmento o tutti</td> <td>Raro, e dovrebbe sembrare raro</td> </tr> </tbody></table> <p>La maggior parte dei team costruisce solo il terzo, lo manda a tutti, e conclude che le email di aggiornamento prodotto non funzionano. I primi due portano quasi tutto il valore, perché il lettore ha un motivo precedente per interessarsi, e il messaggio arriva mentre quel motivo è vivo.</p> <p>Tutte e quattro le righe qui sono scritte per le clienti. Vendite, supporto e customer success devono sapere anche loro cosa è uscito, di solito in una forma diversa da queste quattro; <a href="https://changeloop.dev/blog/it/internal-release-notes/">release note interne</a> copre cosa dovrebbe dire quel documento e perché deve uscire prima di quella rivolta ai clienti.</p> <p>L'email è uno dei diversi canali che un annuncio di lancio può usare, non l'unico. <a href="https://changeloop.dev/blog/it/new-feature-announcement/">Come annunciare una nuova funzionalità</a> copre gli altri, e come scegliere tra loro in base a quanto è grande la funzionalità.</p> <h2>Cosa va nel template?</h2> <p>Sei blocchi, in quest'ordine. Il primo è quello che di solito manca ed è quello che fa il lavoro.</p> <pre><code>Oggetto: <cosa è cambiato, con le parole del lettore> 1. Perché ricevi questa email "Hai chiesto l'export CSV a marzo." oppure "La tua integrazione chiama /v1/invoices, che cambia il 15 gennaio." 2. Cosa è cambiato Una frase. Cosa è ora possibile, o cosa ora si rompe. 3. Cosa devi fare Spesso "niente". Ditelo esplicitamente, non lasciatelo implicito. 4. Dove vederlo Un link alla voce del changelog, non alla homepage. 5. Quando La data in cui è stato rilasciato, o da quando vale. 6. Come annullare l'iscrizione Un clic, e rispettato immediatamente. </code></pre> <p>Il blocco 1 è la differenza tra un messaggio e una diffusione generica. Un lettore a cui viene detto, nella prima riga, che questa è la risoluzione di qualcosa che ha richiesto personalmente, legge il resto. Senza di esso, i blocchi da 2 a 5 sono una newsletter per quanto ben scritta.</p> <p>Tenete l'insieme sotto le circa 150 parole. L'email è un puntatore alla voce del changelog, e la voce è dove appartiene il dettaglio. Un'email che riproduce l'intera voce non dà al lettore un motivo per cliccare, e a voi nessun segnale se è importato a qualcuno.</p> <h2>Quali oggetti funzionano?</h2> <p>Nominate il cambiamento, non la release. "L'export CSV è live" batte "aggiornamenti di settembre" perché il primo è un fatto che il lettore può valutare e il secondo è un contenitore. I numeri di versione nell'oggetto sono utili per chi chiama un'API e rumore per tutti gli altri, un'altra ragione per separare i pubblici.</p> <p>Evitate di affermare un beneficio a cui il lettore non ha acconsentito. "I tuoi report ora sono più veloci" afferma qualcosa sulla sua esperienza; "I report oltre 10.000 righe ora caricano in meno di un secondo" riporta un cambiamento e lascia a lui decidere se conta.</p> <h2>Quando inviarla, e a chi?</h2> <p>Inviate una notifica mirata nel momento in cui la cosa viene rilasciata, alle persone che l'hanno chiesta, individualmente. Inviate un avviso di breaking change non appena la data è certa e di nuovo poco prima, agli account effettivamente coinvolti invece che a tutta la lista. Inviate un digest solo se avete abbastanza cambiamenti da far perdere qualcosa a un lettore altrimenti, e lasciate che le persone si iscrivano separatamente.</p> <p>La lista che quasi non dovreste mai usare è "tutti gli utenti". Trasforma un messaggio specifico in uno generico, e allena l'annullamento dell'iscrizione. Segmentate per comportamento che già memorizzate: chi l'ha chiesto, chi usa questo endpoint, chi è su questo piano.</p> <h2>Serve il consenso per inviarla?</h2> <p>Per i clienti esistenti, un aggiornamento su un servizio che usano è di solito una questione legale diversa dal marketing verso un potenziale cliente, e la risposta dipende da dove si trovano e cosa avete detto loro alla registrazione. Nella UE la domanda rilevante è quale base giuridica dell'<a href="https://gdpr-info.eu/art-6-gdpr/">articolo 6 del GDPR</a> si applica, e negli Stati Uniti i messaggi commerciali portano requisiti specifici indicati nella <a href="https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business">guida alla conformità CAN-SPAM della FTC</a>. Entrambe fanno la stessa richiesta pratica: dite chi siete, chiarite lo scopo, e lasciate che le persone possano fermarsi.</p> <p>Qualunque sia la base, tenete separati i flussi transazionali e di marketing a livello di invio. Un avviso di breaking change che un cliente ha disiscritto perché condivideva una lista con un digest promozionale è un incidente di supporto che aspetta la sua data.</p> <h2>Come si presenta compilata?</h2> <p>La notifica mirata, l'email di aggiornamento prodotto di maggior valore e quella che la maggior parte dei team non costruisce mai:</p> <pre><code>Oggetto: L'export CSV è live Ciao Dana, hai chiesto l'export CSV a marzo. È diventato live stamattina. I report ora hanno un pulsante Export che genera un CSV della vista corrente, filtri inclusi. Niente da fare da parte tua. È già attivo sul tuo account. Dettagli: example.com/changelog#csv-export Rilasciato: 2 settembre 2026 Ricevi questa email perché l'hai chiesta. Annulla iscrizione agli aggiornamenti sulle richieste: <link> </code></pre> <p>Novanta parole, e il lettore sa nella prima riga perché è arrivata. Confrontatela con lo stesso cambiamento in un digest mensile, dove appare come uno tra nove punti e Dana non ha motivo di notare che la sua richiesta è uscita.</p> <h2>Cosa dovreste misurare?</h2> <p>Non il tasso di apertura da solo. Per una notifica mirata la domanda è se la persona che ha chiesto è tornata e ha usato la cosa, quindi il numero da osservare è il clic verso la voce e se quell'account usa la funzione entro una settimana. Per un avviso di breaking change è la copertura: quale quota di account coinvolti ha aperto prima della data, e con chi avete fatto follow-up individuale.</p> <p>Un digest è l'unico dei quattro dove un tasso di apertura conta qualcosa, e anche lì è più utile come tendenza contro la propria storia che contro un benchmark di settore. Tipi diversi di email di aggiornamento prodotto hanno lavori diversi, quindi una cifra mediata su tutti non descrive nulla su cui agire.</p> <h2>In cosa differisce dalle note di rilascio?</h2> <p>Le note di rilascio sono un documento che resta disponibile. L'email è un meccanismo di consegna che accade una volta. Lo stesso cambiamento produce entrambi, e l'email dovrebbe essere più breve della voce a cui rimanda. <a href="https://changeloop.dev/blog/it/release-notes-best-practices/">Note di rilascio: le migliori pratiche</a> copre il documento, e <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">changelog vs note di rilascio</a> copre quale state scrivendo.</p> <p>Il rapporto da far funzionare: la voce del changelog è il testo canonico e l'email lo cita. Quando i due divergono, il lettore che clicca trova una descrizione diversa del cambiamento e smette di fidarsi di entrambi. Pubblicare prima la voce e generare l'email da essa elimina la deriva per costruzione. Changeloop funziona allo stesso modo dal suo lato: una voce viene revisionata e pubblicata una volta su <a href="https://changeloop.dev/docs">pagina, feed e widget</a>, e la persona che l'ha chiesta tramite il widget viene avvisata sull'issue GitHub nato dal suo feedback, e nel widget stesso. Changeloop non invia l'email; il vostro strumento di email cita la voce pubblicata.</p> <h2>FAQ</h2> <p><strong>Con quale frequenza dovrebbe uscire un'email di aggiornamento prodotto?</strong> Tanto spesso quanto c'è qualcosa di specifico che il destinatario vuole sapere, che per una notifica mirata è ogni volta che la sua richiesta viene rilasciata e per un digest al massimo mensile.</p> <p><strong>L'email dovrebbe contenere l'intera voce del changelog?</strong> No. Una frase e un link. La voce è la versione canonica, e una copia completa nell'email significa due testi da mantenere allineati.</p> <p><strong>Che tasso di apertura dovrei aspettarmi?</strong> Confrontate ogni tipo contro se stesso invece che contro un benchmark. Una notifica mirata e un digest mensile sono prodotti diversi, e mediarli nasconde l'unica cifra su cui vale la pena agire.</p> <p><strong>Serve una lista separata per i breaking change?</strong> Sì, e dovrebbe essere quella da cui le persone non possono disiscriversi con noncuranza senza capirne la conseguenza, perché è quella che costa loro un'interruzione.</p> </article> <article> <h1>Come deprecare un'API senza perdere gli sviluppatori</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Deprecare un'API significa annunciare che qualcosa funziona ancora oggi e smetterà di funzionare in una data dichiarata, e poi mantenere entrambe le metà di quella promessa. La maggior parte delle deprecazioni fallisce sulla seconda metà: la data slitta silenziosamente, oppure arriva e i chiamanti che non hanno mai visto l'avviso lo scoprono da un errore. Una deprecazione è finita quando ogni chiamante interessato è migrato o gli è stato detto, individualmente, che non lo è.</p> <h2>Cos'è la deprecazione di un'API?</h2> <p>La deprecazione è il periodo tra l'annuncio che un endpoint, campo o versione sta per sparire e la sua effettiva rimozione. Durante quel periodo il vecchio comportamento continua a funzionare, la documentazione dice che sta per andarsene, e ogni risposta porta un avviso leggibile da macchina. La rimozione è l'evento separato, successivo, spesso chiamato sunset. I due si confondono, e la confusione è dove avviene il danno: "deprecated" inizia a significare "forse è già sparito", e i chiamanti smettono di fidarsi di entrambe le parole.</p> <table> <thead> <tr> <th>Termine</th> <th>Significato</th> <th>Su cosa possono contare i chiamanti</th> </tr> </thead> <tbody><tr> <td>Deprecated</td> <td>Annunciato come in via di sparizione, funziona ancora</td> <td>Comportamento completo fino alla data di sunset</td> </tr> <tr> <td>Sunset</td> <td>La data in cui smette di funzionare</td> <td>Nulla dopo questa data</td> </tr> <tr> <td>Retired / rimosso</td> <td>Sparito; le richieste falliscono</td> <td>Un errore, idealmente uno che nomina il sostituto</td> </tr> <tr> <td>Legacy</td> <td>Indefinito. Evitare la parola</td> <td>Nulla, che è il problema</td> </tr> </tbody></table> <h2>Quanto dovrebbe durare un periodo di deprecazione?</h2> <p>Abbastanza perché un chiamante lo scopra e faccia il lavoro, misurato da quando l'avviso lo ha raggiunto piuttosto che da quando l'avete scritto. Novanta giorni è il minimo comune per un'API web pubblica. Dodici mesi è normale per qualsiasi cosa incorporata in software che gli utenti finali installano, perché la correzione deve passare anche attraverso il loro processo di rilascio. Le linee guida di Google sul versioning, <a href="https://google.aip.dev/185">AIP-185</a>, chiedono un periodo di transizione ragionevole e raccomandano 180 giorni persino prima di rimuovere funzionalità beta, e Kubernetes documenta la sua <a href="https://kubernetes.io/docs/reference/using-api/deprecation-policy/">politica di deprecazione</a> in conteggio di rilasci piuttosto che mesi, che è l'unità corretta quando i vostri chiamanti aggiornano per versione.</p> <p>Scegliete un periodo, scrivetelo come politica, e smettete di deciderlo per ogni cambiamento. Una politica pubblicata trasforma ogni deprecazione da una negoziazione in un'applicazione di una regola.</p> <p>Scrivere la politica di deprecazione copre l'inizio della finestra; <a href="https://changeloop.dev/blog/it/sunsetting-api-version/">ritirare una versione di API</a> copre l'avviso separato necessario alla fine, quando il periodo scade davvero e la versione smette di funzionare.</p> <h2>Il calendario di deprecazione</h2> <p>Quattro date, annunciate insieme il primo giorno. Ciascuna è una voce di changelog separata quando arriva, così la storia viene raccontata quattro volte a chiunque legga solo il changelog.</p> <ol> <li><strong>Annunciare.</strong> La voce dice cosa viene deprecato, perché, cosa lo sostituisce, e la data di sunset. La documentazione della vecchia cosa guadagna un banner che collega alla migrazione. Le risposte guadagnano gli header descritti sotto.</li> <li><strong>Ricordare, a metà strada.</strong> Una seconda voce, e un messaggio diretto a ogni chiamante che ancora usa il vecchio comportamento. Questo è il passo che ha bisogno di dati di utilizzo: se non potete elencare chi sta ancora chiamando l'endpoint deprecato, non potete farlo, e vale la pena risolverlo prima della prossima deprecazione.</li> <li><strong>Brownout, poco prima della data.</strong> Restituite errori per il vecchio comportamento per una finestra breve, un'ora o un giorno, poi ripristinatelo. I chiamanti che hanno perso ogni avviso lo scoprono ora, mentre c'è ancora tempo. GitHub ha usato brownout programmati prima di <a href="https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/">ritirare l'autenticazione con password per l'API</a>, ed è il passo singolo più efficace di questa lista.</li> <li><strong>Sunset.</strong> Rimuovetelo. L'errore che lo sostituisce nomina il sostituto e collega la guida di migrazione. Mantenete l'errore in posizione a lungo; un 404 non dice nulla a un chiamante.</li> </ol> <h2>Cosa dovrebbe dire un avviso di deprecazione?</h2> <p>Un avviso di deprecazione dice cosa sta sparendo, quando smette, cosa usare al suo posto, e chi è interessato. Ecco la forma, compilata:</p> <blockquote> <p><strong><code>GET /v1/reports/daily</code> è deprecato e smette di funzionare il 1° marzo 2027.</strong> È sostituito da <code>GET /v2/reports?granularity=day</code>, che restituisce gli stessi dati con uno schema stabile e paginazione. Interessa le 214 integrazioni che hanno chiamato l'endpoint v1 negli ultimi 30 giorni; se la vostra è una di queste, riceverete anche questo avviso via email. Guida di migrazione: [link]. Nulla cambia fino al 1° marzo 2027. Da quella data l'endpoint v1 restituisce <code>410 Gone</code> con un link a questa voce.</p> </blockquote> <p>Ogni frase porta qualcosa di cui la lettrice ha bisogno. Il conteggio delle integrazioni interessate dice a ciascuna lettrice se continuare a leggere. "Nulla cambia fino a" è la frase che permette a chi non è interessato di chiudere la scheda. La pagina <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> raccoglie voci di team che scrivono questa forma con coerenza, e vale la pena leggerne tre prima di scriverne la prima propria.</p> <h2>Quali header dovrebbe inviare un endpoint deprecato?</h2> <p>Inviate <code>Deprecation</code>, <code>Sunset</code> e un <code>Link</code> al successore, su ogni risposta dall'endpoint deprecato, dal giorno dell'annuncio. L'<a href="https://datatracker.ietf.org/doc/html/rfc9745">header <code>Deprecation</code></a> porta la data in cui la deprecazione è entrata in vigore; l' <a href="https://datatracker.ietf.org/doc/html/rfc8594">header <code>Sunset</code></a> porta la data in cui l'endpoint smette di rispondere; <code>Link: <url>; rel="successor-version"</code> indica cosa usare al suo posto.</p> <pre><code>HTTP/1.1 200 OK Deprecation: @1756425600 Sunset: Mon, 01 Mar 2027 00:00:00 GMT Link: <https://api.example.com/v2/reports>; rel="successor-version" Link: <https://example.com/changelog/daily-reports>; rel="deprecation" </code></pre> <p>La maggior parte dei chiamanti non leggerà mai gli header di persona. Il loro valore sta nel fatto che il client HTTP, il gateway o il monitoraggio di un chiamante possono farlo, il che trasforma la vostra deprecazione in un allarme dalla loro parte piuttosto che una pagina dalla vostra. Gli SDK che spedite dovrebbero registrare un avviso quando ne vedono uno.</p> <h2>Chi è stato informato, e come lo sapete?</h2> <p>Questo è il passo che decide se il sunset è tranquillo o un incidente di supporto, ed è il più difficile da fare solo con un changelog. Una voce di changelog informa chiunque legga il changelog. Una deprecazione deve raggiungere le persone specifiche il cui codice sta per fallire, e il modo abituale di trovarle sono gli stessi dati di utilizzo di cui ha bisogno il promemoria a metà strada: le chiavi API, le app o gli account che hanno chiamato il comportamento deprecato recentemente.</p> <p>Il ciclo che eseguiamo: la voce viene redatta dalla pull request che aggiunge la deprecazione, una persona rivede la formulazione e la data, e una volta pubblicata la voce stessa è la notifica. Chiunque abbia inviato dal widget un feedback sul problema, o una richiesta per il sostituto, diventato un issue GitHub che la pull request chiude, riceve un commento su quell'issue che dice che è stato rilasciato, con un link alla voce. <a href="https://changeloop.dev/docs">Feed e widget</a> servono la stessa voce a tutti gli altri, insieme a ogni altra voce nel <a href="https://changeloop.dev/blog/it/api-changelog/">changelog di API</a>. Ciò che non facciamo è lasciare che la deprecazione diventi "rilasciata" prima che una persona l'abbia pubblicata; un avviso con la data sbagliata è peggio di nessun avviso.</p> <p>Qualunque sia il vostro strumento, la domanda a cui dovete poter rispondere il giorno del sunset è: quali chiamanti stavano ancora usando questo la settimana scorsa, e a quali di loro l'abbiamo detto direttamente? Se la risposta è "abbiamo pubblicato qualcosa a riguardo", il sunset non è pronto.</p> <h2>Qual è la differenza tra deprecare e versionare?</h2> <p>Versionare è come mantenete disponibile il vecchio comportamento mentre esiste il nuovo; deprecare è come ritirate quello vecchio. Una nuova versione API senza una politica di deprecazione per quella precedente è un impegno a mantenere entrambe per sempre. Una deprecazione senza versionamento è un <a href="https://changeloop.dev/blog/it/breaking-changes/">cambiamento che rompe qualcosa</a> con un ritardo. Vi servono entrambi, e la versione è la metà più facile. GraphQL è l'eccezione che vale la pena nominare: di solito non c'è alcun numero di versione da incrementare, e <a href="https://changeloop.dev/blog/it/graphql-schema-deprecation/">deprecazione di schema GraphQL</a> copre come uno schema unico condiviso ritira un campo con una direttiva invece.</p> <h2>FAQ</h2> <p><strong>Un endpoint deprecato dovrebbe continuare a funzionare esattamente come prima?</strong> Sì, fino alla data di sunset. Gli unici cambiamenti permessi sono gli header aggiunti e, verso la fine, un brownout programmato che avete annunciato in anticipo.</p> <p><strong>Quale codice di stato dovrebbe restituire un endpoint ritirato?</strong> <code>410 Gone</code>, con un corpo e un header <code>Link</code> che punta al sostituto e alla voce di changelog. <code>404</code> dice che l'URL non è mai esistito, il che è falso e inutile.</p> <p><strong>Un periodo di deprecazione può essere accorciato?</strong> Solo per sicurezza. Se il vecchio comportamento è sfruttabile, ditelo, accorciate il periodo, e dite a ogni chiamante interessato direttamente piuttosto che affidarvi al changelog.</p> <p><strong>Devo deprecare un campo, o solo interi endpoint?</strong> Campi, parametri, valori enum, default e header hanno tutti bisogno dello stesso trattamento, perché ciascuno può rompere un chiamante corretto. Un campo rimosso è la deprecazione più comune e quella più spesso saltata.</p> </article> <article> <h1>Buone pratiche di versionamento API, per i chiamanti</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Il versionamento API è la pratica di mantenere funzionante un vecchio contratto dopo averlo cambiato, così i chiamanti possono muoversi secondo il proprio calendario invece del vostro. Quella frase contiene le due decisioni che contano: cosa conta come cambiare il contratto, e per quanto tempo continua a funzionare quello vecchio. Dove vive il numero di versione, argomento della maggior parte dei dibattiti sul versionamento, è la meno importante delle tre e la più facile da azzeccare.</p> <h2>Quando si dovrebbe versionare un'API?</h2> <p>Versionate un'API solo quando un cambiamento romperebbe un chiamante corretto. I cambiamenti additivi, nuovi campi, nuovi endpoint, nuovi parametri opzionali, non hanno bisogno di una versione; i chiamanti scritti contro il vecchio contratto continuano a funzionare e la nuova capacità è semplicemente lì. Un <a href="https://changeloop.dev/blog/it/breaking-changes/">cambiamento che rompe qualcosa</a> ne ha bisogno, perché l'alternativa è che un chiamante lo scopra da un errore. Versionare ogni rilascio, inclusi quelli additivi, insegna ai chiamanti che le versioni sono rumore, e smettono di leggere gli avvisi che contano.</p> <p>Il test pratico è lo stesso dell'articolo sui cambiamenti che rompono qualcosa: se un chiamante che dipendeva solo dal comportamento documentato deve cambiare qualcosa per continuare a funzionare, il cambiamento ha bisogno di una versione. Se no, rilasciatelo sotto la versione attuale e scrivete una voce di changelog.</p> <h2>Quale schema di versionamento API si dovrebbe usare?</h2> <p>Usate lo schema che i vostri chiamanti possono vedere e impostare più facilmente, che per la maggior parte delle API pubbliche è una versione nel percorso URL o un header di versione datato. I quattro schemi comuni differiscono meno in capacità che in cosa chiedono al chiamante, e quella è la base giusta per scegliere.</p> <table> <thead> <tr> <th>Schema</th> <th>Esempio</th> <th>Cosa deve fare il chiamante</th> <th>Chi lo usa</th> </tr> </thead> <tbody><tr> <td>Percorso URL</td> <td><code>/v2/invoices</code></td> <td>Cambiare l'URL quando migra</td> <td>La maggior parte delle API REST pubbliche</td> </tr> <tr> <td>Header di versione</td> <td><code>X-GitHub-Api-Version: 2022-11-28</code></td> <td>Inviare un header, o accettare il default</td> <td>GitHub</td> </tr> <tr> <td>Versione account datata</td> <td><code>Stripe-Version: 2026-08-26</code></td> <td>Fissare una data per richiesta o per account</td> <td>Stripe</td> </tr> <tr> <td>Parametro query</td> <td><code>/invoices?version=2</code></td> <td>Aggiungere un parametro</td> <td>API più vecchie; oggi raramente scelto</td> </tr> <tr> <td>Media type</td> <td><code>Accept: application/vnd.example.v2+json</code></td> <td>Negoziare tipi di contenuto</td> <td>Puristi; pochi chiamanti lo padroneggiano</td> </tr> </tbody></table> <p><strong>Percorso URL</strong> è il più visibile e il meno flessibile. Ogni chiamante può vedere in quale versione si trova leggendo una riga di log, e un salto di versione è un cerca-e-sostituisci. Il costo: l'intera superficie si sposta in una volta, non potete cambiare il contratto di un singolo endpoint senza coniare una nuova versione per tutti, così le versioni di percorso tendono a essere rare e grandi.</p> <p><strong>Header di versione</strong> mantiene stabili gli URL e lascia che il server scelga un default per i chiamanti che non inviano nulla, così come funziona il <a href="https://docs.github.com/en/rest/about-the-rest-api/api-versions">versionamento dell'API REST di GitHub</a>: una versione nominata per data in <code>X-GitHub-Api-Version</code>, con la versione supportata più vecchia come default così i chiamanti non versionati non si rompono. Il costo: la versione è invisibile in un URL e facile da dimenticare in un nuovo client.</p> <p><strong>Versione account datata</strong> è lo schema header più un'aggiunta: la versione è memorizzata contro l'account, così ogni richiesta la ottiene senza inviare nulla. Il <a href="https://docs.stripe.com/api/versioning">versionamento API di Stripe</a> fissa ogni account alla versione con cui è stato creato e lascia che una richiesta lo sovrascriva con <code>Stripe-Version</code>. Questo è lo schema più amichevole per il chiamante e quello che richiede più lavoro da gestire, perché il server deve tradurre tra ogni versione supportata e quella attuale.</p> <p><strong>Parametro query</strong> e <strong>media type</strong> funzionano entrambi e falliscono entrambi il test di visibilità in modo diverso: un parametro query si perde facilmente costruendo un URL, e una versione media type è invisibile per quasi qualsiasi strumento con cui un chiamante debugga. Lo schema di Stripe a date è l'esempio più noto dell'approccio per data, e <a href="https://changeloop.dev/blog/it/stripe-api-versioning/">come Stripe versiona la sua API</a> lo ripercorre.</p> <h2>Come si fa il versionamento API in pratica?</h2> <p>In pratica una versione è un insieme nominato di comportamenti, e il server mappa ogni richiesta su uno di essi. I passi sono gli stessi qualunque sia lo schema che porta il nome.</p> <ol> <li><strong>Nominate le versioni per data o per intero, non per versione semantica.</strong> Un'API web non è un pacchetto. I chiamanti non possono fissare una versione minor di un URL, così <code>v2</code> o <code>2026-08-26</code> dice tutto ciò di cui un chiamante ha bisogno, e il <a href="https://semver.org/">versionamento semantico</a> implica una promessa di compatibilità che lo schema non può mantenere.</li> <li><strong>Tenete la versione fuori dai percorsi di codice che non se ne preoccupano.</strong> Una versione dovrebbe selezionare uno strato di traduzione al margine, non biforcare la logica di business. Due copie complete della codebase sono come una versione finisce non mantenuta.</li> <li><strong>Date a ogni versione un default e un documento.</strong> I chiamanti che non inviano versione ricevono la più vecchia supportata, mai la più nuova, così un client non fissato non si rompe il giorno del rilascio. Ogni versione ha una pagina che dice cosa è cambiato rispetto alla precedente.</li> <li><strong>Fissate una finestra di supporto e pubblicatela.</strong> Le linee guida di Google sul versionamento, <a href="https://google.aip.dev/185">AIP-185</a>, chiedono un periodo di transizione ragionevole e ben comunicato e raccomandano 180 giorni persino per le funzionalità beta. Scegliete una finestra, scrivetela, e applicatela senza rinegoziare per versione.</li> <li><strong>Ritirate le versioni come ritirate gli endpoint.</strong> Una versione oltre la sua finestra riceve lo stesso trattamento di qualsiasi <a href="https://changeloop.dev/blog/it/api-deprecation/">API deprecata</a>: un annuncio, un header <code>Sunset</code> (<a href="https://datatracker.ietf.org/doc/html/rfc8594">RFC 8594</a>) su ogni risposta, un promemoria a metà strada ai chiamanti rimasti, e una data di rimozione che tiene.</li> </ol> <h2>Cosa sono v1 e v2 in un'API REST?</h2> <p><code>v1</code> e <code>v2</code> sono nomi per due contratti che lo stesso server supporta contemporaneamente. Un <code>v2</code> esiste perché qualcosa in <code>v1</code> non poteva essere cambiato senza rompere i suoi chiamanti, così il cambiamento è andato in un nuovo contratto e quello vecchio ha continuato a funzionare. I numeri non implicano che <code>v2</code> sia completo o che <code>v1</code> sia morto; entrambe le cose sono vere solo se la documentazione lo dice. Un <code>v3</code> che appare ogni trimestre è un segno che si stanno versionando cambiamenti additivi, o che il contratto non è mai stato progettato per assorbire il cambiamento. gRPC risolve lo stesso problema diversamente: <a href="https://changeloop.dev/blog/it/grpc-protobuf-api-changes/">cambiamenti API gRPC e Protobuf</a> copre il versionamento tramite il nome del package in un file <code>.proto</code> invece di un percorso URL, e un formato di wire dove rinominare un campo è gratis ma rinumerarlo è un breaking change che nessun chiamante REST riconoscerebbe come rischioso.</p> <h2>Cosa dovrebbe annunciare un cambio di versione?</h2> <p>Un cambio di versione dovrebbe annunciare cosa rompe, chi interessa, come migrare, e per quanto tempo continua a funzionare la versione precedente. La voce ha la stessa forma di qualsiasi altra voce di cambiamento che rompe qualcosa, più una riga con la finestra di supporto. Eccone una per un'API versionata per header:</p> <blockquote> <p><strong>La versione API 2026-11-01 è disponibile. La versione 2025-06-15 è supportata fino al 1° novembre 2027.</strong> Nuovo in 2026-11-01: <code>GET /invoices</code> restituisce <code>amount</code> in unità minime come intero invece che come stringa decimale, e il campo deprecato <code>customer_name</code> viene rimosso a favore dell'oggetto <code>customer</code>. Interessa i chiamanti su 2025-06-15 che parsano <code>amount</code> come stringa, che è il default per client non fissati creati prima di giugno 2025. Migrazione: parsate <code>amount</code> come intero e leggete il nome da <code>customer.name</code>. Fissate <code>X-Api-Version: 2026-11-01</code> quando siete pronti. Nulla cambia per i chiamanti che non fissano versione.</p> </blockquote> <p>L'ultima frase è quella che permette alla maggior parte delle lettrici di smettere di leggere, e appartiene a ogni annuncio di versione. La pagina <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> include voci di API che versionano così, e la differenza tra le buone e il resto sta soprattutto in quell'ultima frase.</p> <h2>Chi viene informato quando cambia una versione?</h2> <p>Tutti sulla versione vecchia, individualmente, e il changelog per tutti gli altri. Un cambio di versione è l'unico caso in cui "abbiamo pubblicato qualcosa a riguardo" garantisce di perdere esattamente i chiamanti che contano: quelli che hanno fissato una versione due anni fa e non hanno letto una nota di rilascio da allora. I dati di utilizzo rispondono chi sono; l'avviso deve raggiungerli dove sta il loro codice, negli header di risposta e in un messaggio alla proprietaria dell'account.</p> <p>Nel ciclo che eseguiamo, la voce che annuncia una versione viene redatta dalla pull request che la rilascia, revisionata da una persona, e pubblicata su <a href="https://changeloop.dev/docs">feed e widget</a>, dove un client versionato può leggerla come JSON. Chi ha chiesto il cambiamento, o ha segnalato il bug che risolve, con un feedback dal widget diventato un issue GitHub che la pull request chiude, viene informato su quell'issue non appena la voce viene pubblicata. Il meccanismo è lo stesso di qualsiasi voce; un salto di versione è solo la voce con la posta più alta.</p> <h2>FAQ</h2> <p><strong>Ogni cambiamento API dovrebbe ottenere una nuova versione?</strong> No. Solo i cambiamenti che rompono qualcosa. I cambiamenti additivi si rilasciano sotto la versione attuale con una voce di changelog. Versionare i cambiamenti additivi insegna ai chiamanti a ignorare le versioni.</p> <p><strong>È meglio il versionamento URL o quello per header?</strong> Il versionamento URL è più facile da vedere per i chiamanti e più difficile da far evolvere pezzo per pezzo per voi; quello per header è il contrario. Per un'API pubblica con molti piccoli client, il versionamento URL fallisce meno. Per un'API grande con strato di traduzione, la versione datata per header scala meglio.</p> <p><strong>Quante versioni dovrebbero essere supportate contemporaneamente?</strong> Il meno possibile secondo la vostra finestra di supporto, e mai un numero illimitato. Due o tre versioni concorrenti è normale; più di quello di solito significa che le versioni non vengono ritirate.</p> <p><strong>Cosa dovrebbero ricevere le richieste non versionate?</strong> La versione supportata più vecchia, così i client esistenti non fissati continuano a funzionare, con un header di risposta che dice loro quale versione hanno ricevuto.</p> </article> <article> <h1>Cambiamenti che rompono: cosa conta e come rilasciarli</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un cambiamento che rompe qualcosa è un cambiamento che un chiamante scritto correttamente non avrebbe potuto sopravvivere. La definizione conta perché la maggior parte delle discussioni su se qualcosa "conta" sono in realtà discussioni su chi lo teneva in modo sbagliato. Se un chiamante ha seguito la vostra documentazione e il vostro cambiamento ha fatto smettere di funzionare il suo codice, il cambiamento rompeva qualcosa. Cosa intendevate voi non c'entra nulla.</p> <p>Questo è tutto il test. Il resto di questo articolo è ciò che ne deriva: cosa lo fallisce, cosa lo supera, come intercettare un fallimento prima del merge, e cosa fare una volta che sapete di stare rilasciando un cambiamento che rompe qualcosa.</p> <h2>Cosa conta come cambiamento che rompe qualcosa?</h2> <p>Applicate il test al chiamante, non al diff. Un cambiamento rompe qualcosa quando un chiamante che dipendeva solo dal comportamento documentato deve cambiare il suo codice, la sua configurazione o i suoi dati per continuare a funzionare. Rimuovere un campo, rinominare un endpoint, irrigidire la validazione, cambiare un default e cambiare il tipo di un valore si qualificano tutti. Aggiungere un campo opzionale no. Correggere un bug di solito no, con un'eccezione importante più sotto.</p> <table> <thead> <tr> <th>Cambiamento</th> <th>Rompe qualcosa?</th> <th>Perché</th> </tr> </thead> <tbody><tr> <td>Rimuovere o rinominare un campo, endpoint, flag o opzione</td> <td>Sì</td> <td>I chiamanti corretti lo referenziano</td> </tr> <tr> <td>Aggiungere un campo opzionale o un nuovo endpoint</td> <td>No</td> <td>Le chiamate esistenti non cambiano</td> </tr> <tr> <td>Rendere obbligatorio un input opzionale</td> <td>Sì</td> <td>Le chiamate che lo omettevano ora falliscono</td> </tr> <tr> <td>Irrigidire una validazione prima accettata</td> <td>Sì</td> <td>Input che funzionavano ora vengono rifiutati</td> </tr> <tr> <td>Cambiare un valore di default</td> <td>Sì</td> <td>I chiamanti che non l'hanno impostato ricevono comportamento nuovo</td> </tr> <tr> <td>Cambiare un tipo (stringa a numero, valore singolo ad array)</td> <td>Sì</td> <td>I parser scritti per il tipo documentato falliscono</td> </tr> <tr> <td>Riordinare le chiavi di un oggetto</td> <td>No</td> <td>A meno che abbiate documentato l'ordine</td> </tr> <tr> <td>Correggere un bug su cui i chiamanti facevano affidamento</td> <td>In pratica sì</td> <td>Vedi la sezione sui contratti accidentali</td> </tr> <tr> <td>Alzare un rate limit o un tetto di dimensione</td> <td>No</td> <td>Nulla che funzionava smette di funzionare</td> </tr> <tr> <td>Abbassare un rate limit o un tetto di dimensione</td> <td>Sì</td> <td>Traffico che andava bene ora viene limitato</td> </tr> <tr> <td>Cambiare la formulazione di un messaggio d'errore</td> <td>Dipende</td> <td>Rompe qualcosa se l'avete documentato o i chiamanti fanno match su di esso</td> </tr> </tbody></table> <h2>Cosa non è un cambiamento che rompe qualcosa?</h2> <p>Un cambiamento non rompe nulla quando ogni chiamata che funzionava prima funziona ancora, invariata, e significa ancora la stessa cosa. Aggiungere un nuovo endpoint, aggiungere un parametro opzionale alla richiesta, aggiungere un campo a una risposta, rendere opzionale un input obbligatorio, alzare un limite e migliorare un messaggio d'errore su cui nessuno fa match superano tutti il test. Questi cambiamenti additivi possono andare in un rilascio minor con una voce di changelog ordinaria.</p> <p>I cambiamenti additivi rompono comunque i chiamanti in tre situazioni. Un client il cui deserializzatore rifiuta i campi sconosciuti fallisce al primo nuovo campo della risposta, quindi documentate fin dall'inizio che i chiamanti devono ignorare i campi che non riconoscono. Un nuovo valore di enum rompe qualsiasi chiamante con uno switch esaustivo (ne parliamo più sotto). E una risposta che cresce può spingere un chiamante oltre un limite di dimensione, un timeout o una larghezza di colonna a cui non aveva mai dovuto pensare.</p> <p>Quattro righe della tabella meritano uno sguardo più attento, perché è lì che avvengono i disaccordi.</p> <h2>I quattro cambiamenti che rompono qualcosa che i team trascurano</h2> <p><strong>Contratti accidentali.</strong> Se la vostra API ha restituito lo stesso campo non documentato per tre anni, un chiamante ci ha costruito sopra. La <a href="https://www.hyrumslaw.com/">legge di Hyrum</a> è la versione breve: con abbastanza utenti, ogni comportamento osservabile del vostro sistema sarà dipeso da qualcuno. Ecco perché "era una correzione di bug" non è una difesa. La correzione può essere corretta e rompere comunque qualcosa. Rilasciatela come tale.</p> <p><strong>Cambiamenti comportamentali senza cambiamento di schema.</strong> Il campo è ancora lì, il tipo è lo stesso, e il valore ora significa qualcosa di diverso. Uno <code>status</code> che prima era <code>active</code> o <code>inactive</code> e ora restituisce anche <code>suspended</code> rompe ogni chiamante con uno switch esaustivo. Un timestamp che passa da ora locale a UTC rompe chiunque non abbia letto due volte la documentazione. Nulla in un diff del file OpenAPI mostra queste cose.</p> <p><strong>Validazione irrigidita.</strong> Iniziate a rifiutare email senza TLD, o spazi finali, o nomi più lunghi di 80 caratteri. Ogni chiamante che inviava esattamente quello ora riceve un 400 per una richiesta che funzionava la settimana scorsa. I cambiamenti di validazione sono i più comuni rilasciati come correzione di "irrigidimento".</p> <p><strong>Default cambiati.</strong> Nessuno che ha impostato il valore esplicitamente nota nulla. Tutti quelli che non l'hanno fatto, che sono la maggior parte dei chiamanti, ricevono comportamento nuovo senza cambiare una riga. Un default cambiato rompe la maggioranza dei vostri utenti proprio perché non hanno mai visto l'impostazione.</p> <h2>Come si individua un cambiamento che rompe qualcosa prima del rilascio?</h2> <p>Confrontate il contratto della pull request con quello del branch principale, in CI, e fate fallire la build in caso di differenza che rompe qualcosa. Esistono strumenti di diff degli schemi per la maggior parte dei formati di interfaccia, e ciascuno conosce le regole di rottura del proprio formato:</p> <table> <thead> <tr> <th>Interfaccia</th> <th>Strumento</th> <th>Cosa confronta</th> </tr> </thead> <tbody><tr> <td>REST (OpenAPI)</td> <td><a href="https://github.com/oasdiff/oasdiff">oasdiff</a></td> <td>Due specifiche OpenAPI, con un report dei cambiamenti che rompono qualcosa</td> </tr> <tr> <td>gRPC (Protobuf)</td> <td><a href="https://buf.build/docs/breaking/">buf breaking</a></td> <td>File <code>.proto</code>, a livello wire o di sorgente</td> </tr> <tr> <td>GraphQL</td> <td><a href="https://github.com/kamilkisiela/graphql-inspector">GraphQL Inspector</a></td> <td>Due schemi, segnalando i cambiamenti che rompono e quelli pericolosi</td> </tr> <tr> <td>Crate Rust</td> <td><a href="https://github.com/obi1kenobi/cargo-semver-checks">cargo-semver-checks</a></td> <td>L'API pubblica contro l'ultima versione pubblicata</td> </tr> <tr> <td>Pacchetti TypeScript</td> <td><a href="https://api-extractor.com/">API Extractor</a></td> <td>Un report committato dell'API pubblica del pacchetto</td> </tr> </tbody></table> <p>Questi strumenti intercettano in modo affidabile campi rimossi, operazioni rinominate e tipi cambiati. Non possono vedere i primi due dei quattro tipi sopra, un contratto accidentale o un cambiamento comportamentale, perché nessuno dei due compare in uno schema. Usate lo strumento per fermare quelli ovvi e la domanda di revisione "un chiamante corretto potrebbe accorgersene?" per gli altri. Lo stesso job di CI è il posto naturale per richiedere una voce di changelog, come descritto in <a href="https://changeloop.dev/blog/it/changelog-ci-enforcement/">far rispettare le voci di changelog in CI</a>, e <a href="https://changeloop.dev/blog/it/grpc-protobuf-api-changes/">le modifiche alle API gRPC e Protobuf</a> tratta i casi a livello wire.</p> <h2>Come si segna un cambiamento che rompe qualcosa in un commit?</h2> <p>Con i <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a>, un cambiamento che rompe qualcosa si segna con un <code>!</code> prima dei due punti (<code>feat(api)!: remove the legacy export endpoint</code>) oppure con un footer che inizia con <code>BREAKING CHANGE:</code> seguito da una descrizione. Entrambi corrispondono a una versione major. Scrivete il footer come prima bozza della voce di changelog, indicando chi è interessato e cosa deve fare. <a href="https://changeloop.dev/blog/it/conventional-commits-changelog/">Conventional commits e il changelog</a> spiega fin dove vi porta la convenzione.</p> <p>La stessa regola vale per le librerie. Una funzione pubblica rimossa, un tipo di parametro ristretto o un valore di ritorno cambiato è una versione major nel versionamento semantico. Le librerie non sempre la rispettano: uno <a href="https://arxiv.org/abs/2110.07889">studio su 119.879 aggiornamenti di Maven Central</a> ha rilevato che il 16,6% violava il versionamento semantico, ma solo il 7,9% dei progetti client ne è stato toccato, perché la maggior parte di quei cambiamenti riguardava codice che nessun client chiamava. La rottura si misura sul chiamante.</p> <h2>Come si rilascia un cambiamento che rompe qualcosa?</h2> <p>Lo si rilascia apertamente, con una data, con un percorso. I passi sotto sono in ordine, e l'ultimo è quello che la maggior parte dei team salta: dire alle persone interessate che ciò che stavano aspettando è ora accaduto.</p> <ol> <li><strong>Decidete se lo è.</strong> Usate il test sopra, non il diff. Se due ingegneri non sono d'accordo, rompe qualcosa; il disaccordo è prova che un chiamante avrebbe potuto ragionevolmente fare affidamento sul vecchio comportamento.</li> <li><strong>Versionatelo.</strong> Sotto <a href="https://semver.org/">versionamento semantico</a> un cambiamento che rompe qualcosa è una versione major. Se gestite un'API datata o versionata, va in una nuova versione e quella vecchia continua a funzionare fino a una data dichiarata. Se non potete versionare, non state rilasciando un cambiamento che rompe qualcosa, state rilasciando un'interruzione con una voce di changelog. Quale schema porta la versione è l'argomento di <a href="https://changeloop.dev/blog/it/api-versioning-best-practices/">buone pratiche di versionamento API</a>.</li> <li><strong>Scrivete la voce prima che il codice venga mergiato.</strong> La voce ha una forma fissa: cosa cambia, chi interessa, cosa devono fare, ed entro quando. Se non potete riempire tutte e quattro, il cambiamento non è pronto. La <a href="https://changeloop.dev/release-notes-template">release notes template</a> mette queste voci per prime, con una data invece di un numero di versione, esattamente per questo.</li> <li><strong>Date una scadenza, non un numero di rilascio.</strong> "Rimosso in v5" non significa nulla per chi non segue i vostri rilasci. "Smette di funzionare il 1° novembre 2026" significa la stessa cosa per tutti.</li> <li><strong>Fornite la migrazione.</strong> Un esempio di codice della vecchia chiamata accanto alla nuova. Se il cambiamento è una rinomina, dite entrambi i nomi nella stessa frase. Se è un campo rimosso, dite dove sono andati i dati.</li> <li><strong>Annunciatelo ovunque il vecchio comportamento fosse documentato.</strong> Il changelog, la pagina docs che descrive l'endpoint, le release notes dell'SDK, e l'header di deprecazione nella risposta se ne avete uno.</li> <li><strong>Chiudete il ciclo.</strong> Se una cliente ha chiesto il cambiamento, o ha segnalato il bug che vi ha portato, ditele quando viene rilasciato.</li> </ol> <h2>Come appare una buona voce per un cambiamento che rompe qualcosa?</h2> <p>Una buona voce nomina il chiamante interessato nella prima riga, dichiara la data, e include la correzione. Eccone una per il caso di validazione irrigidita, nella forma che usiamo:</p> <blockquote> <p><strong>Gli indirizzi email senza dominio vengono rifiutati dal 1° novembre 2026.</strong> <code>POST /users</code> e <code>PATCH /users/:id</code> attualmente accettano valori <code>email</code> come <code>alice@localhost</code>. Dal 1° novembre questi restituiscono <code>400 invalid_email</code>. Interessa qualsiasi integrazione che crea utenti da directory interne. Migrazione: inviate un indirizzo completamente qualificato, o omettete il campo e impostatelo dopo. Nessun cambiamento necessario se i vostri indirizzi hanno già un dominio, il che è vero per il 99,4% degli account creati quest'anno.</p> </blockquote> <p>Dove va questo avviso, e cos'altro dovrebbe accompagnarlo, è il tema di <a href="https://changeloop.dev/blog/it/api-changelog/">changelog di API</a>.</p> <p>La percentuale in fondo non è decorazione. Dice alla lettrice se deve preoccuparsi, che è la domanda con cui ha aperto la voce.</p> <h2>Perché non evitarli semplicemente?</h2> <p>Perché l'alternativa è peggiore. Un'API che non rompe mai nulla accumula ogni errore che ha mai fatto: il campo con nome sbagliato, il default sbagliato, il timestamp in ora locale. Ciascuno è una tassa su ogni nuovo chiamante per sempre, per proteggere chiamanti che avrebbero potuto migrare in un pomeriggio. I team con la migliore reputazione di stabilità rompono le cose raramente, secondo un calendario, con un percorso di migrazione e un avviso che ha raggiunto le persone per cui era destinato.</p> <p>La meccanica di quell'avviso è l'argomento dell'articolo compagno su <a href="https://changeloop.dev/blog/it/api-deprecation/">deprecare un'API</a>. La voce che lo annuncia viene redatta nello stesso modo di qualsiasi altra voce nel <a href="https://changeloop.dev/docs">feed del changelog</a>: dalla pull request mergiata, trattenuta per un umano, poi pubblicata nel posto dove i chiamanti interessati già leggono.</p> <h2>FAQ</h2> <p><strong>Qual è la differenza tra un cambiamento che rompe qualcosa e uno che non lo fa?</strong> Un cambiamento che rompe qualcosa costringe un chiamante corretto a modificare codice, configurazione o dati per continuare a funzionare. Uno che non rompe nulla lascia funzionare ogni chiamata esistente con lo stesso significato, ed è per questo che le aggiunte di solito sono sicure mentre rimozioni, rinomine e regole irrigidite di solito no.</p> <p><strong>Conta aggiungere un campo obbligatorio?</strong> Sì. Ogni chiamata esistente lo omette, quindi ogni chiamata esistente ora fallisce. Aggiungetelo come opzionale con un default sensato, o versionate l'endpoint.</p> <p><strong>Conta una correzione di bug?</strong> Può essere. Se i chiamanti dipendevano dal comportamento con il bug, correggerlo li rompe, qualunque cosa dicesse la documentazione. Trattate qualsiasi correzione che cambia l'output osservabile come un cambiamento che rompe qualcosa, a meno che non possiate dimostrare che nessuno ne dipendeva.</p> <p><strong>Il versionamento semantico si applica a un'API web?</strong> La regola sì: i cambiamenti che rompono qualcosa ottengono una nuova versione major e quella vecchia continua a funzionare per un periodo dichiarato. Il numero spesso vive nell'URL o in un header di data piuttosto che in una versione di pacchetto.</p> <p><strong>Quanto preavviso è sufficiente?</strong> Abbastanza perché un chiamante trovi l'avviso e faccia il lavoro. Novanta giorni è un minimo comune per API pubbliche; più lungo per qualsiasi cosa usata in codice spedito a utenti finali e che non può essere aggiornato da remoto.</p> </article> <article> <h1>Chiudere il ciclo di feedback dal changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un ciclo di feedback del cliente si chiude quando alla persona che ha dato il feedback viene detto cosa ne è stato fatto. Non quando viene archiviato. Non quando viene prioritizzato. Nemmeno quando viene rilasciato. Quando le viene detto. La maggior parte dei team fa bene i primi tre passi e per niente l'ultimo, e poi si chiede perché le persone che mandano feedback smettono di mandarlo.</p> <p>Questo articolo riguarda quell'ultimo passo, e un'affermazione concreta: il changelog è il posto giusto da cui chiudere il ciclo, perché è l'unico artefatto che già esiste esattamente nel momento in cui il ciclo può essere chiuso.</p> <h2>Cos'è un ciclo di feedback del cliente?</h2> <p>Un ciclo di feedback del cliente è il percorso da un'utente che vi dice qualcosa a quell'utente che scopre cosa avete fatto al riguardo. Ha quattro passi: raccogliere il feedback, decidere cosa farne, rilasciare il risultato, e avvisare chi ha chiesto. Il ciclo è aperto finché non avviene il quarto passo. Un team che raccoglie feedback e rilascia correzioni ma non avvisa mai nessuno ha una casella di posta, non un ciclo.</p> <table> <thead> <tr> <th>Passo</th> <th>Cosa succede</th> <th>Dove di solito si rompe</th> </tr> </thead> <tbody><tr> <td>Raccogliere</td> <td>Arriva il feedback: widget, supporto, vendite, interviste</td> <td>Niente; ogni team lo fa</td> </tr> <tr> <td>Decidere</td> <td>Viene smistato, unito ai duplicati, accettato o rifiutato</td> <td>I rifiuti non vengono mai comunicati</td> </tr> <tr> <td>Rilasciare</td> <td>Qualcuno lo costruisce ed esce in produzione</td> <td>Il link alla richiesta si perde al merge</td> </tr> <tr> <td>Avvisare</td> <td>Chi ha chiesto scopre che è stato rilasciato</td> <td>Saltato, o fatto solo per chi si è lamentato di più</td> </tr> </tbody></table> <p>L'ultima riga è quella di cui parla questo articolo. Si rompe per una ragione strutturale, non culturale: quando una funzionalità viene rilasciata, la richiesta che l'ha causata vive in un sistema diverso dalla cosa rilasciata, e non è compito di nessuno collegarle. Il ciclo comincia prima, da come si chiede la richiesta fin dall'inizio; <a href="https://changeloop.dev/blog/it/how-to-ask-for-customer-feedback/">come chiedere feedback ai clienti</a> tratta formulazione e tempistica.</p> <h2>Perché i cicli di feedback restano aperti?</h2> <p>I cicli di feedback restano aperti perché la richiesta e il cambiamento rilasciato vivono in posti diversi e il collegamento tra i due viene fatto a mano, quando va bene. La richiesta è in uno strumento di feedback, una casella di supporto o un foglio di calcolo. Il cambiamento è in una pull request. L'annuncio è in un changelog o un'email. Tre sistemi, tre proprietari, e il collegamento dal terzo indietro al primo è una persona che si ricorda, mesi dopo, chi ha chiesto.</p> <p>C'è una seconda ragione. Il passo dell'avviso viene solitamente inquadrato come un compito di marketing ("annunciare la funzionalità") piuttosto che un compito di supporto ("rispondere alla persona"). Gli annunci vanno a tutti e non raggiungono nessuno in particolare. La persona che ha chiesto la funzionalità a marzo legge l'annuncio a giugno, se lo legge, come notizia, non come risposta. Il ciclo si chiude solo se il messaggio è indirizzato a lei.</p> <h2>Perché chiudere il ciclo dal changelog?</h2> <p>Perché la voce di changelog è l'unico artefatto che esiste esattamente al momento giusto, contiene esattamente le parole giuste, ed è scritta esattamente dalla persona giusta. Esiste quando il cambiamento è live e non prima. Dice cosa è cambiato nei termini della lettrice, che è il messaggio di cui ha bisogno chi ha chiesto. Ed è scritta da qualcuno che ha appena letto la pull request, che è l'unico momento in cui il link alla richiesta originale è ancora visibile.</p> <p>Confrontate le alternative. Chiudere il ciclo dallo strumento di feedback significa che lo strumento di feedback deve sapere quando la funzionalità è stata rilasciata, il che significa che qualcuno aggiorna uno stato a mano. Chiuderlo dalla pull request significa avvisare la cliente al merge, prima che il cambiamento sia live, una promessa rotta con timestamp appena il rilascio slitta. Chiuderlo dall'annuncio marketing significa aspettarne uno, e la maggior parte dei cambiamenti rilasciati non ne ha mai uno.</p> <p>Il changelog sta nel mezzo: dopo il merge, al momento del rilascio, con la formulazione pronta.</p> <h2>Come si chiude il ciclo, passo per passo</h2> <p>Questo è il meccanismo che eseguiamo. È descritto qui come specifica piuttosto che tour di prodotto, perché ogni passo può essere fatto a mano o con altri strumenti; quello che conta è l'ordine.</p> <ol> <li><strong>Il feedback diventa un issue nel repository che lo risolverà.</strong> Un invio da widget viene archiviato come issue etichettato su GitHub (<code>feature-request</code> o <code>bug</code>, una priorità, e <code>from-widget</code>), con l'indirizzo email di chi lo ha inviato tenuto fuori dal corpo dell'issue. L'issue vive accanto al codice, così il passo tre può trovarlo. Un issue aperto a mano, per esempio da una <a href="https://changeloop.dev/blog/it/feature-request-template/">template di richiesta funzionalità</a>, è fuori da questo percorso: il passo cinque non lo commenta, quindi quel ciclo chiudetelo voi.</li> <li><strong>La correzione referenzia l'issue.</strong> La pull request dice <code>Fixes #142</code>, la parola chiave di chiusura di GitHub stessa. Niente di nuovo da imparare, ed è la stessa frase che le sviluppatrici scrivono già.</li> <li><strong>La voce di changelog viene redatta dalla pull request mergiata e porta il link.</strong> Al merge, la bozza viene creata e <code>#142</code> viene letto dal corpo della PR e allegato alla bozza. Il link viene creato mentre è ancora economico, da una macchina, da dati che sono già lì.</li> <li><strong>Una persona revisiona la voce.</strong> Formulazione, pubblico, se dovrebbe essere pubblicata affatto. Una bozza scartata non chiude nulla, il che è corretto: un refactor interno che per caso ha referenziato un issue non è notizia.</li> <li><strong>All'approvazione, chi ha chiesto viene informato.</strong> Un commento viene pubblicato sull'issue nato dal suo feedback, "Shipped —" seguito dal titolo della voce e un link alla voce pubblicata, e il widget mostra a chi l'ha inviato la stessa voce rilasciata. Una volta, mai due, e solo dopo che una persona ha pubblicato la voce. La stessa voce esce tramite <a href="https://changeloop.dev/docs">feed e widget</a> a tutti quelli che non hanno chiesto.</li> </ol> <p>L'ordine nel passo cinque è tutto il design. Avvisare chi ha chiesto al merge sarebbe più presto e più facile, e sarebbe sbagliato circa tanto spesso quanto slittano i rilasci. Un feature flag rompe persino quest'ordine, perché approvato e pubblicato può succedere mentre la funzionalità resta invisibile per l'account di chi ha fatto la richiesta; <a href="https://changeloop.dev/blog/it/feature-flags-feature-requests/">feature flag e richieste di funzionalità</a> copre il controllo extra di cui questo passaggio ha bisogno appena c'è di mezzo un flag.</p> <h2>Come appare un ciclo chiuso per la cliente?</h2> <p>Sembra una risposta. La cliente ha inviato una richiesta tramite un widget, e un giorno il widget la mostra come rilasciata, con link a una voce che la descrive nei suoi termini; su GitHub, l'issue riceve la stessa notizia come commento. Non si è iscritta a una newsletter, non ha controllato una roadmap, non ha cercato nel changelog. Le è stato detto.</p> <p>Questa è l'esperienza che fa succedere il prossimo pezzo di feedback. Le persone mandano feedback a prodotti che rispondono. La pagina <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> include voci di team i cui utenti tornano visibilmente con richieste, e il filo comune non è lo strumento; è che le voci si leggono come risposte.</p> <h2>Come si misura un ciclo di feedback?</h2> <p>Misurate la frazione di cambiamenti rilasciati che hanno informato almeno chi ha chiesto, e il tempo dal rilascio all'avviso. Due numeri, entrambi facili una volta che il link esiste e impossibili prima.</p> <ul> <li><strong>Tasso di chiusura</strong>: delle voci di changelog pubblicate questo mese, quante collegavano almeno una richiesta, e di quelle, quante hanno avvisato chi ha chiesto. Se il secondo numero è molto più basso del primo, le notifiche stanno fallendo; se il primo è basso, le richieste non vengono referenziate dalle pull request, e la correzione è una frase nel template della PR.</li> <li><strong>Tempo dal rilascio all'avviso</strong>: quanto passa tra la voce che va live e l'avviso a chi ha chiesto. Col meccanismo sopra sono secondi. A mano sono tipicamente settimane, o mai, e "mai" è il numero che conta.</li> </ul> <p>Non misurate il ciclo per volume di feedback raccolto. Raccogliere è il passo facile, e un team che lo misura lo ottimizzerà, il che produce più cicli aperti.</p> <h2>Dove si inserisce la roadmap?</h2> <p>Una roadmap pubblica è un modo di chiudere il ciclo in anticipo: dice a chi ha chiesto che la sua richiesta è stata ascoltata, prima che venga rilasciata. È utile, e non sostituisce l'ultimo passo. "Pianificato" è una promessa sul futuro; "Rilasciato" è un fatto sul presente. Eseguite la <a href="https://changeloop.dev/blog/it/public-roadmap/">roadmap pubblica</a> dagli stessi issue, con un'etichetta per colonna, così che la stessa richiesta si sposti da pianificata a rilasciata senza essere reinserita da nessuna parte. Lo spostamento a rilasciata è un cambio di etichetta (<code>roadmap:shipped</code>) che nessuno fa per voi quando la voce viene approvata, quindi fatelo nella stessa revisione.</p> <h2>FAQ</h2> <p><strong>Quali sono i quattro passi di un ciclo di feedback del cliente?</strong> Raccogliere, decidere, rilasciare, avvisare. Il ciclo è aperto finché non avviene il quarto passo. La maggior parte dei framework aggiunge passi di analisi e prioritizzazione nel mezzo; sono raffinamenti di "decidere", e nessuno di essi chiude nulla.</p> <p><strong>Si dovrebbe avvisare i clienti quando si rifiuta una richiesta?</strong> Sì, ed è il messaggio più trascurato del ciclo. Un chiaro "non lo faremo, ed ecco perché" finisce l'attesa. Il silenzio lascia il ciclo aperto per sempre e la cliente a controllare.</p> <p><strong>In cosa si differenzia chiudere il ciclo dall'annunciare una funzionalità?</strong> Un annuncio va a tutti. Chiudere il ciclo è una risposta alle persone che hanno chiesto, sul canale attraverso cui hanno chiesto. Fate entrambe le cose; sono messaggi diversi per lettrici diverse.</p> <p><strong>E se chi ha chiesto non è su GitHub?</strong> La maggior parte non lo è, e va bene così. Il widget continua a mostrargli lo stato di ciò che ha inviato, compresa la voce rilasciata e il suo link, quindi non gli serve nulla oltre alla pagina da cui ha scritto. Il commento sull'issue è per le persone che possono vedere il repository.</p> <p><strong>Questo ciclo funziona su GitLab o Bitbucket invece che su GitHub?</strong> Il widget e il changelog sì; il commento automatico del passo cinque no, per ora. Un team su GitLab o Bitbucket riceve comunque ogni invio, lo archivia comunque come issue, e mostra comunque a chi ha chiesto uno stato nel widget, ma chiudere quello specifico ciclo tornando sull'issue stesso è un passo che si fa a mano finché quell'integrazione non esiste.</p> </article> <article> <h1>Template di richiesta funzionalità che diventa changelog</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Un template di richiesta funzionalità è un modulo con quattro domande: cosa sta cercando di fare la persona, cosa glielo impedisce, cosa ha provato invece, e come vuole essere avvisata quando è fatto. Tutto il resto che di solito appare su uno, selettori di priorità, stime di sforzo, punteggi di valore business, è per il team che riceve la richiesta, e viene compilato male da chi la invia.</p> <p>Le richieste ordinate sono il test sbagliato per un template. Quello giusto: sei mesi dopo, quando la funzionalità viene rilasciata, qualcuno può trovare la richiesta, capirla, e avvisare chi l'ha scritta? La maggior parte dei template sono progettati per l'ammissione. Questo è progettato per il giorno in cui si chiude il ciclo.</p> <h2>Cosa dovrebbe includere un template di richiesta funzionalità?</h2> <p>Dovrebbe includere l'obiettivo, il blocco, la soluzione alternativa, e un modo per tornare a chi ha chiesto. Quattro campi, in quest'ordine, ciascuno risponde a una domanda che il team farà dopo.</p> <table> <thead> <tr> <th>Campo</th> <th>La domanda a cui risponde dopo</th> <th>Perché è nel modulo</th> </tr> </thead> <tbody><tr> <td>Cosa stai cercando di fare?</td> <td>La funzionalità costruita è quella di cui c'era bisogno?</td> <td>L'obiettivo sopravvive a qualsiasi proposta concreta</td> </tr> <tr> <td>Cosa te lo impedisce oggi?</td> <td>Come appare "fatto"?</td> <td>Nomina il vuoto senza prescrivere la correzione</td> </tr> <tr> <td>Cosa fai invece?</td> <td>Quanto è urgente davvero?</td> <td>Una soluzione alternativa dolorosa è un segnale più forte di un selettore di priorità</td> </tr> <tr> <td>Come dovremmo avvisarti?</td> <td>Chi riceve il messaggio "rilasciato"?</td> <td>Il campo che la maggior parte dei template omette</td> </tr> </tbody></table> <p>Ciò che manca deliberatamente: una soluzione proposta come campo obbligatorio (benvenuta come commento, sbagliata come inquadratura), un selettore di priorità (chiunque invii sceglie alta), e qualsiasi stima di sforzo o valore (compito del team, dopo lo smistamento). Un template che chiede una soluzione riceve richieste di pulsanti; un template che chiede un obiettivo riceve richieste di risultati, e su risultati si scrive una voce di changelog.</p> <h2>Il template</h2> <p>Questo è il template di issue GitHub che usiamo, come modulo. Incollatelo in <code>.github/ISSUE_TEMPLATE/feature_request.yml</code> e viene reso come modulo strutturato nella pagina nuovo issue. Le richieste archiviate attraverso di esso diventano issue con gli stessi campi di quelle archiviate da un widget di feedback, il che conta per la sezione successiva.</p> <pre><code class="language-yaml">name: Feature request description: What you are trying to do, and what stops you. labels: ["feature-request"] body: - type: textarea id: goal attributes: label: What are you trying to do? description: >- The outcome, not the button. "Export a month of invoices as one PDF" beats "add a PDF export". validations: required: true - type: textarea id: blocker attributes: label: What stops you today? description: >- Where the product runs out. An error, a missing option, a limit. validations: required: true - type: textarea id: workaround attributes: label: What do you do instead? description: >- The spreadsheet, the script, the manual step. "Nothing, I gave up" is a valid answer. - type: input id: contact attributes: label: How should we tell you when it ships? description: >- An email address, or leave blank to be notified only on this issue. </code></pre> <p>Due dettagli fanno il lavoro. <code>labels: ["feature-request"]</code> significa che la richiesta viene classificata alla creazione, invece di aspettare che qualcuno la smisti. E l'ultimo campo esiste perché "ti faremo sapere" è una promessa, e una promessa ha bisogno di un indirizzo.</p> <h2>Quali etichette dovrebbe portare una richiesta di funzionalità?</h2> <p>Una richiesta di funzionalità dovrebbe portare un'etichetta per cosa è, una per quanto è urgente, e una per da dove è arrivata. Tre etichette, tre assi, e ciascuno viene letto da una lettrice diversa.</p> <table> <thead> <tr> <th>Etichetta</th> <th>Valori</th> <th>Chi la legge</th> </tr> </thead> <tbody><tr> <td>Tipo</td> <td><code>feature-request</code>, <code>bug</code></td> <td>Chi decide in quale coda entra</td> </tr> <tr> <td>Priorità</td> <td><code>priority:low</code>, <code>priority:medium</code>, <code>priority:high</code></td> <td>Chi pianifica il prossimo ciclo</td> </tr> <tr> <td>Origine</td> <td><code>from-widget</code>, <code>from-form</code>, <code>from-support</code></td> <td>Chi misura da dove arrivano le richieste</td> </tr> </tbody></table> <p>Il widget applica i primi due assi e <code>from-widget</code> quando archivia un invio come issue; <code>from-form</code> e <code>from-support</code> sono suggerimenti per le richieste che arrivano per altre vie. Le etichette del widget sono un tipo (<code>bug</code> o <code>feature-request</code>, deciso da un classificatore solo dal messaggio), una priorità (una segnalazione di crash calma e concreta è alta; un duplicato di qualcosa già chiesto è bassa; qualsiasi cosa che anche solo accenni a un problema di sicurezza è <code>bug</code> e alta, qualunque sia la formulazione), e <code>from-widget</code>. Gli stessi tre assi funzionano per richieste che arrivano a mano attraverso il template sopra, ed è questo il punto: una richiesta è una richiesta, indipendentemente da dove sia entrata.</p> <p>Un'altra convenzione: il widget rimuove l'indirizzo email di chi invia dal corpo dell'issue prima di archiviarlo, perché l'issue vive in un repository che può essere pubblico, e lo sostituisce con un riferimento di invio. L'indirizzo resta fuori dall'issue; chi ha inviato segue l'esito nel widget stesso. Fate lo stesso col campo di contatto se il vostro tracker è visibile a persone fuori dal team.</p> <h2>Come diventa una richiesta di funzionalità una voce di changelog?</h2> <p>Una richiesta di funzionalità diventa una voce di changelog quando una pull request chiude l'issue e la voce redatta da quella pull request collega indietro. Il meccanismo sono le parole chiave di chiusura di GitHub stessa: una PR la cui descrizione dice <code>Fixes #142</code> chiude l'issue 142 al merge. Se le vostre voci di changelog sono redatte da pull request mergiate, la bozza può portare con sé il numero dell'issue, e la voce sa chi ha chiesto.</p> <p>Questa è la ragione per cui il template chiede l'obiettivo piuttosto che la soluzione. Quando si scrive la voce, l'obiettivo è la frase di cui ha bisogno chi scrive: "Ora puoi esportare un mese di fatture come un unico PDF" è una voce di changelog. "Aggiunto export PDF" è un messaggio di commit. Gli <a href="https://changeloop.dev/changelog-tools">strumenti per il changelog</a> che redigono da pull request possono fare la raccolta e il collegamento; la formulazione ha ancora bisogno di una persona, e la persona ha bisogno dell'obiettivo.</p> <h2>Cosa succede quando viene rilasciato?</h2> <p>A chi ha chiesto viene detto, con link alla voce. Nel nostro setup questo è automatico per le richieste arrivate tramite il widget: un commento che dice "Shipped — <titolo della voce>" con link alla voce pubblicata, pubblicato sull'issue non appena una persona approva la voce, mentre il widget mostra a chi ha inviato la stessa voce. Un issue aperto a mano da questo template non riceve alcun commento automatico; quel ciclo chiudetelo voi, con la stessa regola. Il commento viene pubblicato deliberatamente all'approvazione, non al merge: un commento che dice che qualcosa è live prima che lo sia è una promessa rotta con timestamp. Ogni richiesta viene notificata al massimo una volta; una seconda approvazione della stessa voce non produce un secondo commento.</p> <p>Se lo fate a mano, vale la stessa regola. Non chiudete il ciclo dalla pull request. Chiudetelo dalla voce pubblicata, e chiudetelo una volta. <a href="https://changeloop.dev/docs">Feed e widget</a> portano la stessa voce a tutti quelli che non hanno chiesto, che sono la maggior parte; il commento è per chi ha chiesto.</p> <h2>Perché falliscono la maggior parte dei template di richiesta funzionalità</h2> <p>Sono progettati per rendere più facile lo smistamento e ci riescono, a costo dell'unico momento che conta per chi ha chiesto. Un template con dodici campi riceve meno richieste, e quelle che riceve vengono da persone con la pazienza di compilare dodici campi, che non è la stessa popolazione di chi ha bisogno della funzionalità. Un template con quattro campi, uno dei quali è "come ti contattiamo", riceve più richieste e può onorarle tutte.</p> <h2>FAQ</h2> <p><strong>Un template di richiesta funzionalità dovrebbe chiedere la priorità?</strong> No. Chiedete invece la soluzione alternativa. "Esporto in un foglio di calcolo e lo ridigito ogni venerdì" dice più sulla priorità di un menu a tendina che chi invia ha messo su alta.</p> <p><strong>Chi chiede dovrebbe proporre una soluzione?</strong> Può, nel testo libero. Non fatene l'inquadratura. Le richieste scritte come soluzioni sono più difficili da fondere tra loro e più difficili da trasformare in una voce di changelog.</p> <p><strong>Le richieste di funzionalità dovrebbero apparire su una roadmap pubblica?</strong> Una volta pianificate, sì: un'etichetta sullo stesso issue la mette nella colonna pianificata, e chi ha chiesto può vedere come si muove. L'articolo <a href="https://changeloop.dev/blog/it/public-roadmap/">roadmap pubblica</a> è il meccanismo.</p> <p><strong>Come gestisco i duplicati?</strong> Collegate la nuova richiesta all'issue esistente ed etichettatela priorità bassa; non chiudetela. Ogni duplicato è una persona in più da avvisare quando viene rilasciato. Con il commento automatico di Changeloop, quella persona viene avvisata solo se la pull request nomina anche il suo issue (<code>Fixes #142, fixes #187</code>).</p> <p><strong>Dove dovrebbe vivere il template?</strong> Nel repository che riceverà la pull request, così che funzioni la parola chiave di chiusura. Una richiesta in un tracker separato deve essere collegata a mano al merge, ed è quel passo a essere saltato.</p> </article> <article> <h1>Roadmap pubblica dal vostro issue tracker, tre colonne</h1> <p>Sat, 29 Aug 2026 00:00:00 GMT</p> <p>Una roadmap pubblica è una lista di ciò che intendete costruire, pubblicata dove i clienti possono vederla. La parola che fa il lavoro è <em>intendete</em>: una roadmap è un insieme di promesse sul futuro, e ogni elemento su di essa è uno che manterrete o si vedrà che non mantenete. Questa è la ragione per pubblicarne una, ed è anche la ragione per cui la maggior parte delle roadmap pubbliche diventano obsolete entro un trimestre. La versione che sopravvive è piccola, derivata da dati che già mantenete, e collegata all'altro capo al changelog, così che una promessa diventi un fatto senza che nessuno la reinserisca.</p> <h2>A cosa serve una roadmap pubblica?</h2> <p>Una roadmap pubblica dice a una cliente con una richiesta che la richiesta è stata ascoltata, prima che venga rilasciata. È la metà anticipata della chiusura del ciclo: "pianificato" risponde alla domanda "qualcuno lo ha letto", e "in costruzione" risponde a "sta davvero succedendo". Nessuno dei due sostituisce l'ultimo passo, avvisare chi ha chiesto quando viene rilasciato, ma entrambi riducono il numero di persone che chiedono nel frattempo.</p> <p>Fa anche una cosa per il team: forza un impegno pubblico, che è la cura più economica conosciuta per un backlog che nasconde silenziosamente quattrocento elementi che nessuno costruirà.</p> <table> <thead> <tr> <th>Colonna</th> <th>La promessa che fa</th> <th>Cosa sposta un elemento dentro</th> </tr> </thead> <tbody><tr> <td>Pianificato</td> <td>Intendiamo costruire questo</td> <td>Una decisione, registrata come etichetta sull'issue</td> </tr> <tr> <td>In costruzione</td> <td>Qualcuno ci sta lavorando ora</td> <td>Un'etichetta <code>roadmap:building</code> sull'issue</td> </tr> <tr> <td>Rilasciato</td> <td>È live</td> <td>Un'etichetta <code>roadmap:shipped</code>, o la chiusura dell'issue mentre ce l'ha</td> </tr> </tbody></table> <p>Tre colonne, in ordine fisso, sono sufficienti. Una quarta colonna ("in considerazione", "in revisione", "backlog") è dove le buone intenzioni diventano un museo, ed è la prima che i clienti imparano a ignorare.</p> <h2>La vostra roadmap dovrebbe essere pubblica?</h2> <p>Rendetela pubblica se potete mantenerla piccola e onesta; tenetela privata se l'alternativa è una lunga lista di forse. Il costo di una roadmap pubblica non ha nulla a che fare col pubblicarla: ogni elemento su di essa è ora una domanda che qualcuno farà, nel supporto, nelle chiamate di vendita e nelle conversazioni di rinnovo. Dieci elementi che costruirete sono un asset. Sessanta elementi che potreste costruire sono sessanta conversazioni future sul perché no.</p> <p>Due ragioni oneste per non pubblicare: i vostri piani cambiano più veloce di un trimestre, o la vostra concorrenza legge la vostra roadmap più attentamente dei vostri clienti. Entrambe sono reali, ed entrambe si risolvono pubblicando meno piuttosto che niente: solo "in costruzione", con "pianificato" tenuto interno, dice comunque a chi ha chiesto che il suo issue si sta muovendo.</p> <h2>Come si costruisce una roadmap pubblica dagli issue di GitHub?</h2> <p>Mettete un'etichetta per colonna sugli issue che già tracciate, e rendete gli issue etichettati come la roadmap. Niente viene reinserito, la roadmap non può divergere dal lavoro, e lo stesso issue che è iniziato come richiesta di un cliente si muove attraverso le colonne senza cambiare identità.</p> <p>Il meccanismo, così come lo eseguiamo:</p> <ol> <li><strong>Un'etichetta per colonna, con prefisso fisso</strong>: <code>roadmap:planned</code>, <code>roadmap:building</code>, <code>roadmap:shipped</code>. Qualsiasi issue in un repository collegato che ne porti una appare in quella colonna. Un issue senza nessuna di esse non è sulla roadmap, che è la maggior parte degli issue, il che è corretto.</li> <li><strong>Le colonne sono un array ordinato, sempre nello stesso ordine.</strong> Pianificato, in costruzione, rilasciato. Non una mappa indicizzata per nome, così che una lettrice (o un widget) non debba mai indovinare la sequenza.</li> <li><strong>Se un issue porta due etichette, vince la più avanzata.</strong> Qualcuno aggiungerà <code>roadmap:shipped</code> prima di rimuovere <code>roadmap:planned</code>; una macchina a stati guidata da "quale webhook è arrivato per ultimo" metterebbe l'elemento in colonne diverse a seconda dell'ordine di consegna. Decidere solo dall'insieme di etichette rende la risposta uguale indipendentemente da come arrivano gli eventi.</li> <li><strong>Rilasciato è uno stato di etichetta come gli altri.</strong> La carta si sposta quando l'issue riceve <code>roadmap:shipped</code>, o viene chiuso mentre ce l'ha. La carta in sé non collega alla voce di changelog; la voce, redatta dalla pull request che ha chiuso l'issue, è dove vivono i dettagli.</li> <li><strong>Servitela come dati.</strong> La roadmap è un documento JSON con quelle tre colonne, pubblicato accanto al feed di changelog con gli stessi header di cache, così che un sito docs, un widget o una pagina di stato possano renderla senza una seconda integrazione. La <a href="https://changeloop.dev/docs">documentazione del feed</a> ha la forma esatta.</li> </ol> <p>Un'etichetta è poco da chiedere a una mantenitrice, ed è tutta l'integrazione. Nessuna board da mantenere sincronizzata, nessuno strumento separato in cui accedere, e la richiesta che la cliente ha archiviato è l'elemento sulla roadmap; quando viene rilasciato, è lo stesso elemento.</p> <h2>Cosa non dovrebbe contenere una roadmap pubblica?</h2> <p>Non dovrebbe contenere date, stime, o nulla di cui vi vergognereste se vi venisse chiesto tra nove mesi. Le date sono l'errore classico: un trimestre su una roadmap diventa un impegno in una presentazione di vendita diventa un ticket chiamato "avete detto Q3". Le colonne dicono abbastanza. "In costruzione" significa già "abbastanza presto che qualcuno ci sta lavorando".</p> <p>Non dovrebbe nemmeno contenere il backlog interno. Una roadmap con trecento elementi è un problema di ricerca, non una promessa, e la cliente che trova la sua richiesta in posizione 212 ha imparato qualcosa che non volevate dirle.</p> <h2>Come si collega la roadmap al changelog?</h2> <p>La roadmap e il changelog descrivono gli stessi issue da due lati, uno per il futuro e uno per il passato. Nessuno sposta una carta su una board separata. Una mantenitrice cambia l'etichetta sull'issue su cui stava già lavorando, la voce viene redatta dalla pull request, e quando una persona approva quella voce chi ha chiesto, se il suo feedback dal widget è diventato quell'issue, viene informato lì. Spostare la carta in rilasciato resta un passo a sé, l'etichetta <code>roadmap:shipped</code>, quindi fatelo parte della stessa revisione; approvare la voce non lo fa per voi.</p> <p>Questo è lo stesso ciclo che descrive l'<a href="https://changeloop.dev/blog/it/customer-feedback-loop/">articolo sul ciclo di feedback</a> dal lato del changelog; la roadmap è ciò che la cliente vede nel mezzo di esso. La rassegna <a href="https://changeloop.dev/changelog-tools">strumenti per il changelog</a> copre quali prodotti offrono una vista roadmap e quali la trattano come una board separata, che è la differenza che decide se resta accurata.</p> <h2>Come appare una buona roadmap pubblica?</h2> <p>Sembra corta, e ogni elemento su di essa è un issue che qualcuno può aprire. Il test è se una cliente può andare da un elemento alla discussione dietro di esso, e da un elemento rilasciato alla voce che descrive cosa è effettivamente cambiato. Una roadmap che è una lista di nomi di funzionalità senza modo di entrare è una brochure.</p> <p>Un esempio lavorato, come il JSON che un widget andrebbe a recuperare:</p> <pre><code class="language-json">{ "columns": [ { "column": "planned", "hasMore": false, "items": [ { "id": "6b0c1f...", "column": "planned", "publicTitle": "Saved views on the inbox", "publicDescription": "Keep a filter you use often and come back to it.", "publishedAt": "2026-09-16T10:04:11.000Z" } ]}, { "column": "building", "hasMore": false, "items": [ { "id": "71a4e2...", "column": "building", "publicTitle": "Roadmap column in the widget", "publicDescription": "See what is coming without leaving the page.", "publishedAt": "2026-09-12T08:20:02.000Z" } ]}, { "column": "shipped", "hasMore": false, "items": [ { "id": "5c9d70...", "column": "shipped", "publicTitle": "Feedback filed as labelled issues", "publicDescription": "Widget submissions arrive as issues your triage already handles.", "publishedAt": "2026-09-02T15:41:37.000Z" } ]} ], "enabled": true, "language": "en" } </code></pre> <p>Tre elementi su tre colonne sono una roadmap pubblica perfettamente buona. Dice cosa sta arrivando, cosa sta succedendo, e cosa è successo, e ogni riga di essa è verificabile. Altri cinque layout, da Now/Next/Later a quello per risultati, sono mostrati con voci di esempio negli <a href="https://changeloop.dev/blog/it/product-roadmap-examples/">esempi di roadmap di prodotto</a>.</p> <h2>FAQ</h2> <p><strong>Quanti elementi dovrebbe avere una roadmap pubblica?</strong> Il meno possibile che potete difendere. Meno di dieci in totale è normale per un prodotto piccolo; più di trenta in "pianificato" è un backlog travestito da roadmap.</p> <p><strong>Una roadmap pubblica dovrebbe avere date?</strong> No. Le colonne comunicano sequenza senza creare una scadenza. Se una cliente ha bisogno di una data, quella è una conversazione, non un elemento di roadmap.</p> <p><strong>I clienti dovrebbero votare sugli elementi della roadmap?</strong> I voti misurano chi si è presentato, non cosa conta. Un commento sull'issue che spiega la soluzione alternativa che usano oggi vale più di cinquanta voti, e costa qualcosa a chi vota, che è il punto.</p> <p><strong>Cosa succede a un elemento della roadmap che viene cancellato?</strong> Rimuovete l'etichetta e dite perché sull'issue. Un "non lo faremo" pubblico è parte del ciclo, ed è il messaggio che la maggior parte dei team non invia mai.</p> </article> <article> <h1>Automazione del changelog, e i suoi limiti</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>L'automazione del changelog funziona quando automatizza raccolta, classificazione e pubblicazione, e si ferma a selezione e formulazione. Automatizzate tutto e spedite un git log formattato; non automatizzate nulla e il changelog viene scritto a raffiche, a memoria, prima dei rilasci. La domanda utile è quali parti automatizzare, non quanto.</p> <p>I progetti di automazione del changelog falliscono in una di due direzioni, ed entrambe sono prevedibili dal primo incontro di design. Automatizzate troppo poco e il changelog è un documento che qualcuno dovrebbe aggiornare, il che significa che viene aggiornato a raffiche, da chi ha pescato la cannuccia più corta. Automatizzate troppo e diventa un git log formattato: completo, accurato, e letto da nessuno.</p> <h2>Quali parti di un changelog dovrebbero essere automatizzate?</h2> <p>Tre dei quattro passi. Raccolta e pubblicazione completamente; classificazione come prima passata con override umano; selezione e formulazione mai.</p> <table> <thead> <tr> <th>Passo</th> <th>Automatizzare?</th> <th>Perché</th> </tr> </thead> <tbody><tr> <td>Raccolta: cambiamenti da commit, PR, ticket in una lista</td> <td>Completamente</td> <td>Noioso, saltato sotto scadenza, le macchine lo fanno perfettamente</td> </tr> <tr> <td>Classificazione: Added, Fixed, Changed, Deprecated, Removed, Security</td> <td>Prima passata, override umano</td> <td>Circa l'80% corretto solo dai metadati; il 20% sbagliato sono le voci che contano</td> </tr> <tr> <td>Selezione e formulazione: cosa dire al lettore, e come</td> <td>Mai</td> <td>È tutto il valore dell'artefatto</td> </tr> <tr> <td>Pubblicazione: pagina, feed, email, widget, Slack</td> <td>Completamente, da una fonte</td> <td>Dove va la maggior parte dello sforzo manuale reale</td> </tr> </tbody></table> <p><strong>Raccolta.</strong> Portare i cambiamenti dal luogo dove accadono (commit, PR, ticket) in una lista. Automatizzate questo completamente. Gli umani sono scarsi in questo, è noioso, ed è il passo che viene saltato sotto scadenza. <a href="https://changeloop.dev/blog/it/conventional-commits-changelog/">Conventional commits</a> o le etichette PR sono la materia prima abituale.</p> <p><strong>Classificazione.</strong> Decidere se qualcosa è Added, Fixed, Changed, Deprecated, Removed o Security. Automatizzate la prima passata dal tipo di commit o dall'etichetta PR, e lasciate che un umano faccia override. La precisione qui è intorno all'ottanta percento solo dai metadati, e il venti percento sbagliato è concentrato esattamente nelle voci che contano, perché l'ambiguità correla con il significato.</p> <p><strong>Selezione e formulazione.</strong> Decidere cosa dovrebbe sapere un lettore e come dirlo. <strong>Non automatizzate questo.</strong> È tutto il valore dell'artefatto. Tutto il resto è logistica.</p> <p><strong>Pubblicazione.</strong> Portare le voci finite su una pagina, un feed, un'email, un widget in-app, un canale Slack. Automatizzate completamente, e da una fonte. Qui va la maggior parte dello sforzo manuale reale, e quasi nessuno lo conta. È anche il passo che può dire a chi ha chiesto il cambiamento che è stato rilasciato, che è tutto il tema di <a href="https://changeloop.dev/blog/it/customer-feedback-loop/">chiudere il ciclo di feedback dal changelog</a>. La metà email di quel passo ha una sua forma propria, nel <a href="https://changeloop.dev/blog/it/product-update-email/">template email di aggiornamento prodotto</a>.</p> <p>Quest'ultimo punto merita di essere considerato. I team tendono a vedere il changelog come un problema di scrittura, e poi passano la maggior parte del tempo sulla distribuzione: copiare voci in uno strumento email, riformattare per l'in-app, incollare su Slack, aggiornare una pagina docs. La scrittura richiede un'ora. La copia richiede un'ora per ogni rilascio, per sempre, ed è la parte che dovrebbe avere una macchina.</p> <h2>Cosa succede quando il confine si sposta?</h2> <p><strong>Spostatelo in alto e ottenete un dump di git.</strong> L'automazione totale dai commit produce <code>bump deps</code>, <code>fix flaky test</code>, <code>wip</code> e <code>address review comments</code> davanti ai clienti. Ogni team che lo ha fatto ha poi aggiunto un filtro, e il filtro è un passo di selezione reintrodotto sotto un altro nome, con ergonomia peggiore.</p> <p><strong>Spostatelo in basso e ottenete raffiche.</strong> La raccolta totalmente manuale significa che le voci vengono scritte a memoria al momento del rilascio. Quella è la modalità contro cui <a href="https://changeloop.dev/blog/it/keep-a-changelog-implemented/">Keep a Changelog</a> avverte fin dall'inizio, e si degrada silenziosamente: il changelog sembra mantenuto fino alla settimana in cui nessuno ha avuto tempo.</p> <h2>Come appare una pipeline di automazione del changelog?</h2> <p>Quattro passi, con esattamente un cancello umano, posto dove una bozza diventa pubblica.</p> <ol> <li>Al merge, derivate una voce bozza dalla PR: tipo da etichetta o prefisso commit, titolo come prima bozza, link di ritorno alla PR, autrice registrata. Fatela atterrare in un cassetto non rilasciato.</li> <li>Chiunque può editare qualsiasi bozza in qualsiasi momento, e editare è economico. La maggior parte riceve una riga riscritta.</li> <li>Tagliare un rilascio richiede che ogni voce nel cassetto sia o editata o marcata esplicitamente come interna. Questo cancello è tutto il design. Senza di esso, le bozze vengono rilasciate non editate nella settimana impegnata.</li> <li>Pubblicare è un fan-out dall'insieme rilasciato: la pagina pubblica, il feed, l'email, il widget, il post Slack. Una fonte, più rendering, nessuna copia.</li> </ol> <p>Il passo 3 è l'unico posto dove è richiesta una persona, e richiede circa dieci minuti per rilascio una volta che le bozze sono decenti. Dove è coinvolta una richiesta di un cliente, la bozza porta anche l'issue che chiude, il che è ciò che permette al passo 4 di avvisare chi ha chiesto; la <a href="https://changeloop.dev/blog/it/feature-request-template/">template di richiesta funzionalità</a> è progettata perché quel link sopravviva. Dove si colloca questo passo nel flusso di rilascio più ampio è il tema del <a href="https://changeloop.dev/blog/it/release-management-process/">processo di release management</a>.</p> <h2>Cosa richiede l'automazione dai vostri dati?</h2> <p>Niente di tutto questo funziona se il changelog è un file Markdown, perché un file non può essere reso su cinque superfici senza riparsarlo, e parsare la prosa è come si finisce con un widget che mostra metà titolo.</p> <p>Le voci devono essere strutturate: un tipo, una data, una versione o identificatore di rilascio, un pubblico, un corpo e un link. Allora il file, la pagina, il feed e l'email sono tutte viste. Quel punto strutturale è l'unica cosa che vale la pena fare bene prima di scegliere uno strumento, perché è ciò che non potete aggiungere dopo a basso costo. Niente di tutto questo funziona se poi una voce non viene davvero creata per ogni cambiamento che ne ha bisogno; <a href="https://changeloop.dev/blog/it/changelog-ci-enforcement/">imporre una voce di changelog in CI</a> copre come far rifiutare alla pipeline un merge senza voce, invece di lasciare quel passaggio alla memoria.</p> <p>Costruiamo <a href="https://changeloop.dev/">changeloop</a>, dove il changelog è prima un feed e poi una pagina, quindi leggete questo come un interesse piuttosto che una raccomandazione imparziale; il <a href="https://changeloop.dev/pricing">pricing</a> è un repository gratuito senza carta, sufficiente per vedere la forma. <a href="https://changeloop.dev/changelog-tools">Strumenti per il changelog</a> è la nostra rassegna di cos'altro c'è, inclusi i prodotti con cui competiamo, e il <a href="https://changeloop.dev/changelog-generator">generatore di changelog</a> fa i passi di raccolta e classificazione nel browser se volete vedere la derivazione prima di impegnarvi in una pipeline.</p> <h2>Il test</h2> <p>Contate i minuti tra un cambiamento mergiato e quel cambiamento visibile a una cliente che non legge il vostro repo. Se la maggior parte di quei minuti è qualcuno che copia testo tra strumenti, l'automazione di cui avete bisogno è nella pubblicazione, non nella scrittura.</p> <h2>FAQ</h2> <p><strong>Può l'IA scrivere il changelog?</strong> Può redigerne una bozza. Un modello a cui viene data la pull request mergiata produce la maggior parte delle volte una prima bozza utilizzabile del titolo e del corpo, il che è raccolta e classificazione fatte meglio. La selezione, se dire qualcosa a un lettore, e la formulazione finale, hanno ancora bisogno della persona che conosce il pubblico, e una pipeline che pubblica bozze senza quel cancello ha automatizzato il passo sbagliato.</p> <p><strong>Qual è la differenza tra un generatore di changelog e l'automazione del changelog?</strong> Un generatore trasforma i commit in una lista formattata una volta, su richiesta. L'automazione gira ad ogni merge, mantiene un cassetto non rilasciato, condiziona il rilascio alla revisione umana, e pubblica su ogni superficie da una fonte. Il generatore è il primo passo della pipeline, eseguito a mano.</p> <p><strong>Il changelog dovrebbe essere automatizzato dai commit o dalle pull request?</strong> Dalle pull request, dove l'unità di cambiamento è la PR: il titolo e la descrizione sono scritti una volta, per l'intero cambiamento, e la PR collega l'issue che chiude. La derivazione basata su commit funziona quando il commit è l'unità e segue una convenzione.</p> <p><strong>Come si impedisce all'automazione di pubblicare cambiamenti interni?</strong> Classificate <code>chore</code>, <code>ci</code>, <code>test</code>, <code>refactor</code> e aggiornamenti di dipendenze come interni per default, e rendete la promozione a pubblico un atto deliberato. Il default inverso, pubblico a meno che qualcuno lo nasconda, è come <code>bump deps</code> raggiunge i clienti.</p> </article> <article> <h1>Changelog vs release notes: qual è la differenza?</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>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.</p> <p>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.</p> <h2>Changelog vs release notes, a confronto</h2> <table> <thead> <tr> <th></th> <th>Changelog</th> <th>Release notes</th> </tr> </thead> <tbody><tr> <td>Lettore</td> <td>Qualcuno che cerca qualcosa</td> <td>Qualcuno che decide se interessarsene</td> </tr> <tr> <td>Ambito</td> <td>Tutto ciò che è cambiato</td> <td>Cosa vale la pena dire su questo rilascio</td> </tr> <tr> <td>Cadenza</td> <td>Continua, per merge o per rilascio</td> <td>Per rilascio, e solo quelli che vale la pena annunciare</td> </tr> <tr> <td>Tono</td> <td>Conciso, fattuale, spesso imperativo</td> <td>Esplicativo, a volte persuasivo</td> </tr> <tr> <td>Durata</td> <td>Permanente, letto anche anni dopo</td> <td>Letto la prima settimana, poi archiviato</td> </tr> <tr> <td>Vive in</td> <td>Il repo, un sito docs, una pagina <code>/changelog</code></td> <td>Email, in-app, un post del blog, una pagina di rilascio</td> </tr> <tr> <td>Fallisce per</td> <td>Essere incompleto</td> <td>Essere noioso, o arrivare tardi</td> </tr> </tbody></table> <h2>Cos'è un changelog?</h2> <p>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 <a href="https://changeloop.dev/blog/it/keep-a-changelog-implemented/">Keep a Changelog</a> dedica la maggior parte della sua unica pagina alla struttura e quasi niente alla prosa.</p> <h2>Cosa sono le release notes?</h2> <p>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. <a href="https://changeloop.dev/blog/it/how-to-write-release-notes/">Come scrivere release notes</a> riguarda la selezione e la formulazione.</p> <h2>Servono sia un changelog che le release notes?</h2> <p>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 <code>/changelog</code> 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à.</p> <p>La divisione vale la pena quando iniziano a succedere queste cose:</p> <ul> <li>Le vostre voci di changelog sono cresciute con paragrafi esplicativi che gli sviluppatori scorrono senza leggere.</li> <li>O il contrario: i vostri annunci di rilascio hanno iniziato a elencare aggiornamenti di dipendenze.</li> <li>Il supporto sta copiando voci nelle email e riscrivendole per strada.</li> <li>Qualcuno chiede "solo i cambiamenti che rompono qualcosa" e non potete filtrarli.</li> </ul> <p>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.</p> <h2>Una fonte, due viste</h2> <p>L'errore è trattarli come due documenti. Sono due viste sullo stesso insieme di cambiamenti.</p> <p>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.</p> <p>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. <a href="https://changeloop.dev/blog/it/changelog-automation/">Automazione del changelog</a> 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.</p> <h2>Se avete tempo solo per uno</h2> <p>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à.</p> <p>Mantenetelo in un formato fisso così che la derivazione resti possibile. La nostra pagina di <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> raccoglie voci di team che lo fanno bene, e la <a href="https://changeloop.dev/release-notes-template">release notes template</a> è la forma che usiamo quando trasformiamo un insieme di voci in qualcosa che vale la pena inviare.</p> <h2>Una nota sui nomi</h2> <p>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.</p> <p>Su quale superficie finisca il risultato è una decisione a parte, trattata in <a href="https://changeloop.dev/blog/it/changelog-page/">come costruire una pagina di changelog</a>.</p> <h2>FAQ</h2> <p><strong>Un changelog è lo stesso delle release notes?</strong> 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.</p> <p><strong>Le release notes possono essere generate da un changelog?</strong> 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.</p> <p><strong>Dove dovrebbe vivere un changelog?</strong> Da qualche parte permanente e collegabile a cui il lettore può arrivare senza un repository: una pagina <code>/changelog</code>, un sito docs, o un feed che si rende in più posti. Un <code>CHANGELOG.md</code> da solo raggiunge i collaboratori, non i clienti.</p> <p><strong>Un changelog dovrebbe includere cambiamenti interni?</strong> 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à.</p> </article> <article> <h1>Dai conventional commits a un changelog</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>I conventional commit regalano a un changelog tre cose: il tipo di ogni cambiamento, la parte del sistema che ha toccato, e se rompe qualcosa. Non gli regalano nient'altro. Formulazione, raggruppamento e selezione, che sono il changelog, restano completamente aperti, e una pipeline che finge il contrario spedisce un git log formattato.</p> <pre><code>feat(exports): add CSV column selection fix(auth): reject expired refresh tokens chore(deps): bump node-pg to 8.11 </code></pre> <p>Tre commit nel formato <a href="https://www.conventionalcommits.org/">Conventional Commits</a>. Da questi, una macchina può dirvi che uno è una funzionalità, uno è una correzione, uno è manutenzione, e quale parte del sistema ha toccato ciascuno. Questo è genuinamente utile, ed è tutta la promessa della convenzione: una cronologia dei commit leggibile da qualcosa di diverso da una persona. L'errore è pensare che questo vi dia un changelog. Vi dà la materia prima.</p> <h2>Cosa specifica la convenzione?</h2> <p>Un tipo, uno scope opzionale, e una descrizione: <code>type(scope): description</code>. I tipi convenzionalmente sono <code>feat</code>, <code>fix</code>, <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>perf</code>, <code>build</code>, <code>ci</code>. Due cose segnano un cambiamento che rompe qualcosa: un <code>!</code> prima dei due punti, o un footer <code>BREAKING CHANGE:</code>. Gli strumenti si basano su <code>feat</code> e <code>fix</code> per i bump di versione minor e patch, e sul marcatore di breaking per uno major.</p> <table> <thead> <tr> <th>Il commit vi dà</th> <th>Il changelog ha bisogno di</th> <th>Chi colma il divario</th> </tr> </thead> <tbody><tr> <td><code>feat</code> / <code>fix</code> / <code>chore</code></td> <td>Added / Fixed / interno</td> <td>Una mappatura, automatica</td> </tr> <tr> <td><code>(scope)</code></td> <td>Un raggruppamento che il lettore riconosce</td> <td>Una persona, una volta per scope</td> </tr> <tr> <td><code>!</code> o <code>BREAKING CHANGE:</code></td> <td>Chi si rompe, per quando, e cosa fare</td> <td>Una persona, ogni volta</td> </tr> <tr> <td>La descrizione, scritta per una revisora</td> <td>Il risultato, scritto per una cliente</td> <td>Una persona, ogni voce</td> </tr> <tr> <td>Un commit</td> <td>Un cambiamento, che può essere più commit</td> <td>Regole di squash, o una persona</td> </tr> </tbody></table> <p>Il marcatore lo dice allo strumento; non lo dice al chiamante, che è l'argomento di <a href="https://changeloop.dev/blog/it/api-deprecation/">come deprecare un'API</a> e <a href="https://changeloop.dev/blog/it/breaking-changes/">cos'è un cambiamento che rompe qualcosa</a>. È una specifica piccola e vale la pena seguirla anche se non generate mai nulla da essa, perché forza una decisione per commit: è un cambiamento che gli utenti vedono, o no.</p> <h2>Dove si fermano i conventional commit?</h2> <p>Si fermano alla frase. Tutto ciò che la convenzione cattura sono metadati su un cambiamento; il cambiamento stesso è ancora descritto nel vocabolario di una revisora.</p> <p><strong>I messaggi di commit sono scritti per revisore.</strong> <code>fix(auth): reject expired refresh tokens</code> è corretto e non dice nulla a una cliente. La lettrice di un changelog vuole "verrai disconnesso quando una sessione è davvero scaduta, invece di vedere 401 intermittenti".</p> <p><strong>Gli scope sono interni.</strong> <code>exports</code>, <code>auth</code>, <code>ingest</code> sono nomi di moduli. Sono stabili, il che li rende buoni per raggruppare, e privi di significato per chiunque sia fuori dalla codebase.</p> <p><strong>Un cambiamento è spesso più commit.</strong> Una funzionalità mergiata su undici commit produce undici voci, dieci delle quali rumore, e schiacciarle per nasconderlo perde la cronologia di revisione.</p> <p><strong><code>chore</code> è un cassetto, non una categoria.</strong> Aggiornamenti di dipendenze, cambiamenti CI e rinomine finiscono tutti lì, e alcuni contano per gli utenti mentre la maggior parte no.</p> <p>Quindi: la convenzione vi dà tipo, scope e stato di breaking gratis, e lascia formulazione, raggruppamento e selezione completamente aperti. Quei tre sono il changelog. <a href="https://changeloop.dev/blog/it/changelog-entry-ownership/">A chi appartiene davvero una voce di changelog</a> copre chi dovrebbe occuparsi di quella formulazione, raggruppamento e selezione, dato che la convenzione stessa non ha un'opinione a riguardo.</p> <h2>Come si genera un changelog dai conventional commit?</h2> <p>In due strati, e il secondo deve essere obbligatorio.</p> <p><strong>Strato uno, automatico.</strong> Al merge, derivate una voce bozza dal commit: tipo mappato su un tipo di changelog (<code>feat</code> su Added, <code>fix</code> su Fixed, un marcatore di breaking su Changed più un flag), scope tenuto come metadato piuttosto che come testo, link alla PR. Fatela atterrare nella sezione Unreleased che <a href="https://changeloop.dev/blog/it/keep-a-changelog-implemented/">Keep a Changelog</a> richiede.</p> <p><strong>Strato due, umano, e richiesto.</strong> Prima che esca un rilascio, ogni voce bozza o riceve una riscrittura di una riga nel vocabolario dell'utente, o viene marcata interna e scartata dalla vista pubblica. Questo è il passo che la gente cerca di saltare, e saltarlo è ciò che produce changelog che si leggono come un diff.</p> <p>Il dettaglio importante di design è che lo strato due non è opzionale nella pipeline. Se un rilascio può essere tagliato con bozze non editate, lo sarà, nella settimana in cui tutti sono impegnati. Quali passi appartengono alla macchina e quali alla persona è tutto il tema di <a href="https://changeloop.dev/blog/it/changelog-automation/">automazione del changelog</a>.</p> <p>Tagliare il rilascio è anche il momento in cui un tag git, una release e questa voce di changelog o combaciano o iniziano a disallinearsi; <a href="https://changeloop.dev/blog/it/git-tags-releases-changelog/">tag git, release e il tuo changelog</a> copre come mantenere i tre sincronizzati.</p> <h2>Tre trappole</h2> <p><strong>Gli squash merge mangiano i footer.</strong> Se la vostra piattaforma schiaccia con il titolo della PR come messaggio, il footer <code>BREAKING CHANGE:</code> di un commit dentro quel branch scompare, e il vostro strumento smette silenziosamente di vedere il cambiamento che rompe qualcosa. Controllate cosa mantiene davvero il vostro template di squash.</p> <p><strong>I commit di revert producono voci fantasma.</strong> Un <code>fix</code> che viene revertito il giorno dopo genera una voce per qualcosa che non è mai stato rilasciato, a meno che la derivazione non riconcili i revert. La maggior parte degli strumenti non lo fa.</p> <p><strong>Il bump di versione e il changelog si disallineano.</strong> Se la versione è calcolata dai commit e il changelog è scritto a mano dopo, divergono in circa due rilasci. Calcolate entrambi nello stesso passaggio o accettate che uno dei due sia sbagliato.</p> <h2>Se volete la parte meccanica senza una pipeline</h2> <p>Il nostro <a href="https://changeloop.dev/changelog-generator">generatore di changelog</a> fa il passo di derivazione nel browser: incollate i commit, ottenete voci raggruppate e tipizzate. È deliberatamente deterministico ed interamente lato client, così i commit che incollate non lasciano mai la vostra macchina, il che conta quando i messaggi provengono da un repository privato. Fa onestamente la metà di raccolta e non tenta lo strato due, perché lo strato due è un giudizio e uno strumento che lo finge produce esattamente il changelog contro cui argomenta questo articolo.</p> <p>Per la versione pipeline, <a href="https://changeloop.dev/changelog-tools">strumenti per il changelog</a> copre cosa esiste.</p> <h2>Il riassunto</h2> <p>I conventional commit rispondono "che tipo di cambiamento è questo" in modo affidabile ed economico. Non rispondono "cosa dovremmo dire alla gente", e nessuna quantità di strumenti sopra il messaggio di commit lo farà, perché l'informazione non è mai stata nel messaggio di commit. Mettete in budget la riscrittura.</p> <h2>FAQ</h2> <p><strong>I conventional commit generano automaticamente un changelog?</strong> Generano automaticamente una bozza: voci tipizzate, con scope, collegate. La formulazione per una cliente, il raggruppamento e la decisione su cosa lasciare fuori hanno ancora bisogno di una persona, e una pipeline che salta quel passo pubblica messaggi di commit.</p> <p><strong>Quali tipi di conventional commit appaiono in un changelog?</strong> <code>feat</code> e <code>fix</code> sempre, come Added e Fixed. <code>perf</code> di solito, come Changed. <code>chore</code>, <code>docs</code>, <code>refactor</code>, <code>test</code>, <code>build</code> e <code>ci</code> sono interni per default e appaiono solo se una persona ne promuove uno.</p> <p><strong>Come segnano i conventional commit un cambiamento che rompe qualcosa?</strong> Un <code>!</code> dopo il tipo o lo scope (<code>feat(api)!: ...</code>), o un footer <code>BREAKING CHANGE:</code> nel corpo del commit. Entrambi si perdono se uno squash merge conserva solo il titolo della PR.</p> <p><strong>Servono i conventional commit per automatizzare un changelog?</strong> No. Le etichette PR, i template PR e i link agli issue portano gli stessi metadati per i team che mergiano tramite pull request. I conventional commit sono l'opzione più economica quando l'unità di cambiamento è il commit.</p> </article> <article> <h1>Come scrivere release notes che la gente legge davvero</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Per scrivere release notes che la gente legge, rispondi a una domanda per ogni voce: cosa può fare ora il lettore che prima non poteva, e cosa deve fare al riguardo. Metti per prima qualsiasi cosa con una scadenza, nomina chi è interessato, di' "nessuna azione necessaria" quando è vero, e salta i rilasci che non hanno nulla da dire. Tutto il resto in questa pagina è quella regola applicata.</p> <blockquote> <p>Correzioni di bug e miglioramenti delle prestazioni.</p> </blockquote> <p>Ogni prodotto lo ha pubblicato almeno una volta. La causa raramente è pigrizia: è quello che si ottiene quando le release notes sono scritte dall'interno, da qualcuno che ha passato due settimane nel diff e non riesce più a vedere quali parti importerebbero a uno sconosciuto. Un tono migliore non lo risolverà; rispondere alla domanda sì.</p> <h2>Cosa dovrebbero includere le release notes?</h2> <p>Le release notes dovrebbero includere, per ogni cambiamento degno di nota: cosa può fare ora il lettore, chi è interessato, cosa deve fare al riguardo (incluso "niente"), e quando entra in vigore qualsiasi cosa con una scadenza. Non dovrebbero includere numeri di ticket interni, nomi di componenti usati solo dal team, o un numero di versione come unico titolo.</p> <table> <thead> <tr> <th>Includere</th> <th>Escludere</th> </tr> </thead> <tbody><tr> <td>Il risultato, nei termini del lettore</td> <td>L'implementazione, nei termini del team</td> </tr> <tr> <td>Chi è interessato, per piano, ruolo o versione API</td> <td>"Alcuni utenti"</td> </tr> <tr> <td>L'azione richiesta, o "nessuna azione necessaria"</td> <td>Silenzio, che il lettore riempie con lo scenario peggiore</td> </tr> <tr> <td>Una data per qualsiasi cosa con scadenza</td> <td>Un numero di versione al posto di una data</td> </tr> <tr> <td>Un link alla doc che lo spiega</td> <td>Un link alla pull request</td> </tr> <tr> <td>Bug segnalati dagli utenti, e il limite che è stato alzato</td> <td>Id di ticket interni</td> </tr> <tr> <td>La sezione noiosa, una riga ciascuna, in fondo</td> <td>La sezione noiosa mescolata con le novità</td> </tr> </tbody></table> <p>La divisione tra una release note e una <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">voce di changelog</a> è ciò che rende possibile questa lista: il changelog tiene tutto, così le notes possono lasciare fuori delle cose. Esempi annotati di ogni tipo di voce sono raccolti in <a href="https://changeloop.dev/blog/it/release-notes-examples/">esempi di release notes</a>.</p> <h2>La domanda a cui risponde ogni voce</h2> <p><strong>Cosa può fare ora il lettore che prima non poteva, e cosa deve fare al riguardo?</strong></p> <p>Se una voce non può rispondere a questo, appartiene al changelog e non alle release notes. Entrambe le metà contano. La prima metà è il valore. La seconda metà è quella che i team dimenticano, ed è quella che genera ticket di supporto quando manca.</p> <p>Due esempi della seconda metà che fa un lavoro reale:</p> <ul> <li>"I webhook esistenti continuano a funzionare fino al 1° novembre. Dopo quella data, i payload non firmati verranno rifiutati."</li> <li>"Nessuna azione necessaria. Le esportazioni esistenti vengono ricodificate automaticamente la prossima volta che le apri."</li> </ul> <p>La seconda dice esplicitamente "nessuna azione necessaria". Vale la pena scrivere quella frase ogni singola volta, perché un lettore che non la trova presume il peggio.</p> <h2>Come dovrebbero essere ordinate le release notes?</h2> <p>Ordinale per conseguenza sul lettore, mai per la parte del sistema che è cambiata. Raggruppare per API, dashboard, mobile e infrastruttura è il vostro organigramma, non il problema del lettore.</p> <ol> <li><strong>Cambiamenti che rompono qualcosa e qualsiasi cosa con scadenza.</strong> Sempre per primi, anche se piccoli. Se un lettore smette di leggere dopo una riga, questa è la riga che deve aver letto. Se la scadenza è un sunset, la voce dovrebbe suonare come un <a href="https://changeloop.dev/blog/it/api-deprecation/">avviso di deprecazione</a>.</li> <li><strong>Cosa c'è di nuovo che vorranno.</strong> Uno per paragrafo, con il risultato nella prima frase.</li> <li><strong>Cosa è migliorato.</strong> Bug segnalati, limiti alzati, cose che erano lente.</li> <li><strong>Tutto il resto, come lista.</strong> Aggiornamenti di dipendenze, refactor interni, copy minore. Una riga ciascuno. Nessuno legge questa sezione, e dovrebbe comunque esserci, perché chi la cerca ne ha davvero bisogno.</li> </ol> <h2>La riscrittura</h2> <p>Prima:</p> <blockquote> <p><strong>v4.2.0</strong> Corretto un problema per cui l'endpoint <code>POST /exports</code> restituiva intermittentemente 500 sotto carico. Rifattorizzato il worker di export. Aggiornato <code>node-pg</code> a 8.11. Migliorata la gestione errori nel serializzatore CSV.</p> </blockquote> <p>Dopo:</p> <blockquote> <p><strong>Le esportazioni non falliscono più sugli account grandi.</strong> Gli account con oltre circa 50.000 righe potevano ricevere un 500 all'avvio di un'esportazione, più spesso a fine mese. Questo è risolto, e le esportazioni di qualsiasi dimensione ora si riprovano da sole invece di fallire. Nessuna azione necessaria, e qualsiasi esportazione fallita nell'ultima settimana può semplicemente essere rieseguita.</p> <p>Anche nella 4.2.0: <code>node-pg</code> 8.11, errori più chiari nel serializzatore CSV.</p> </blockquote> <p>Stesso rilascio. La seconda nomina l'account interessato, il momento peggiore, cosa è cambiato, e cosa fare. L'aggiornamento della dipendenza non è scomparso, ha solo smesso di essere il titolo. L'articolo <a href="https://changeloop.dev/blog/it/release-notes-best-practices/">buone pratiche per le release notes</a> ha il resto delle regole che questa riscrittura segue, ciascuna con quanto costa saltarla.</p> <h2>Cose che vale la pena eliminare</h2> <ul> <li><strong>"Siamo entusiasti di annunciare."</strong> Il lettore non è ancora entusiasta. Guadagnatelo nella frase successiva.</li> <li><strong>Numeri di ticket interni.</strong> <code>PROJ-4471</code> non significa nulla fuori dal vostro tracker. Se la voce ha bisogno di un riferimento, linka la pagina della doc.</li> <li><strong>Nomi di componenti usati solo dal vostro team.</strong> Se avete rinominato la "pipeline di ingest", dite "importazioni".</li> <li><strong>Un numero di versione come unico titolo.</strong> <code>v4.2.0</code> è un'etichetta di archiviazione, non un riassunto.</li> <li><strong>Screenshot di una pagina impostazioni che nessuno ha mai visitato.</strong> Mostrate ciò che è cambiato, in uso.</li> </ul> <h2>Con che frequenza si dovrebbero pubblicare le release notes?</h2> <p>Pubblicate quando succede qualcosa, non secondo un calendario. Le note che arrivano ad ogni rilascio addestrano tutti a ignorarle. Le note che arrivano quando succede qualcosa vengono aperte. Va bene, ed è di solito corretto, pubblicare un rilascio senza alcuna nota e far confluire le sue voci nel set successivo che ha un titolo degno di lettura.</p> <p>Il changelog continua a registrare tutto. Questa è la divisione del lavoro: il changelog è completo, le note sono selettive. Se mantieni il changelog strutturato man mano, scrivere le note è selezione e riscrittura, non archeologia.</p> <p>La <a href="https://changeloop.dev/release-notes-template">release notes template</a> è la forma che usiamo per il passaggio di selezione, e <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> raccoglie voci di team il cui changelog è abbastanza buono da derivarne delle note.</p> <p>Tutto questo presuppone una pagina che controlli completamente, senza limite di lunghezza e con link che funzionano. <a href="https://changeloop.dev/blog/it/mobile-app-release-notes/">Release notes per app mobile</a> copre cosa cambia quando la superficie è un elenco App Store o Play Store. <a href="https://changeloop.dev/blog/it/emergency-release-notes/">Release notes di emergenza</a> copre l'altra eccezione: cosa cambia quando non resta più tempo per seguire affatto il normale processo di scrittura.</p> <h2>Un test prima di pubblicare</h2> <p>Leggi le note come qualcuno che è stato in vacanza per due settimane e ha 40 secondi. Se in quel tempo non riesce a capire se gli viene richiesto qualcosa, le note non sono finite, per quanto accurate siano.</p> <h2>FAQ</h2> <p><strong>Quanto dovrebbero essere lunghe le release notes?</strong> Quanto richiedono i cambiamenti con conseguenze, e non un pizzico di più. Un rilascio con un cambiamento che rompe qualcosa e due miglioramenti sono tre paragrafi. Riempire un rilascio tranquillo per farlo sembrare sostanzioso è come i lettori imparano a saltare le note.</p> <p><strong>Chi dovrebbe scrivere le release notes?</strong> La persona che capisce il cambiamento, editata da qualcuno che non lo capisce. L'ingegnera sa cosa è cambiato; l'editrice sa cosa fraintenderà uno sconosciuto. Scrivere la voce al momento del merge, mentre l'ingegnera se lo ricorda ancora, è la pratica che rende tutto questo economico.</p> <p><strong>Le release notes dovrebbero includere correzioni di bug?</strong> Sì, quelle che qualcuno ha segnalato o incontrato. Indica il sintomo visto dal lettore, non la causa. "Le esportazioni oltre 50.000 righe fallivano" è una correzione che un lettore riconosce; "corretta una race condition nel worker di export" è un messaggio di commit.</p> <p><strong>Qual è la differenza tra release notes e un changelog?</strong> Il changelog è il registro completo e continuo; le release notes sono il messaggio curato su un rilascio, scritto per persone che non hanno ancora deciso se interessarsi. La risposta più lunga è in <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">changelog vs release notes</a>.</p> </article> <article> <h1>Keep a Changelog, davvero implementato</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Keep a Changelog è una convenzione di una pagina per un <code>CHANGELOG.md</code>: 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.</p> <p>Olivier Lacan ha pubblicato <a href="https://keepachangelog.com/">Keep a Changelog</a> nel 2014 con una frase invecchiata meglio della maggior parte della prosa sul software: <em>don't let your friends dump git logs into changelogs</em>. 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.</p> <h2>Cosa chiede Keep a Changelog?</h2> <p>Un <code>CHANGELOG.md</code> 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:</p> <table> <thead> <tr> <th>Tipo</th> <th>Per</th> <th>Cosa costa tralasciarlo</th> </tr> </thead> <tbody><tr> <td>Added</td> <td>Nuove funzionalità</td> <td>Niente; nessuno tralascia questo</td> </tr> <tr> <td>Changed</td> <td>Cambiamenti nel comportamento esistente</td> <td>I lettori scoprono un cambiamento di comportamento da un errore</td> </tr> <tr> <td>Deprecated</td> <td>Funzionalità in procinto di essere rimosse</td> <td>Una rimozione diventa un incidente invece di un evento pianificato</td> </tr> <tr> <td>Removed</td> <td>Funzionalità rimosse in questo rilascio</td> <td>Nessuno distingue una rimozione da un bug</td> </tr> <tr> <td>Fixed</td> <td>Correzioni di bug</td> <td>Niente; nessuno tralascia neanche questo</td> </tr> <tr> <td>Security</td> <td>Vulnerabilità</td> <td>L'unica lettrice che la cercava non la trova</td> </tr> </tbody></table> <p>Più una sezione <code>Unreleased</code> in cima, così c'è dove mettere una voce nel momento in cui viene mergiata, e così chiunque può vedere cosa arriva.</p> <p>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.</p> <h2>Quali parti di Keep a Changelog vengono tralasciate?</h2> <p>La sezione Unreleased, poi quattro dei sei tipi, Security tra questi, in quest'ordine.</p> <p><strong><code>Unreleased</code> scompare per prima.</strong> È 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. <a href="https://changeloop.dev/blog/it/changelog-automation/">Automazione del changelog</a> riguarda per lo più tenere viva questa sezione senza che qualcuno debba ricordarselo.</p> <p><strong>I sei tipi collassano in due.</strong> 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 <a href="https://changeloop.dev/blog/it/api-deprecation/">come deprecare un'API</a>.</p> <p><strong>Security smette di essere separato.</strong> 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.</p> <h2>Cosa non risponde la specifica?</h2> <p>È un formato di file. Non dice nulla sulle domande che si incontrano subito dopo averla adottata:</p> <ul> <li><strong>Come lo scopre qualcuno?</strong> Un file in un repo raggiunge i collaboratori. Non raggiunge un cliente che non ha mai aperto GitHub.</li> <li><strong>E i prodotti senza versioni?</strong> 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.</li> <li><strong>Chi scrive la voce?</strong> La specifica assume che lo faccia un umano. Non dice quando.</li> <li><strong>E i pubblici multipli?</strong> 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. <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">Changelog vs release notes</a> è la divisione che la specifica vi lascia fare da soli.</li> </ul> <p><a href="https://common-changelog.org/">Common Changelog</a>, 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.</p> <h2>Si può automatizzare Keep a Changelog senza scaricare git log?</h2> <p>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.</p> <p>La macchina gestisce raccolta e formattazione, in cui è brava. L'umano gestisce selezione e formulazione, in cui non lo è. <a href="https://changeloop.dev/blog/it/conventional-commits-changelog/">Conventional commits</a> 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 <a href="https://changeloop.dev/changelog-tools">strumenti per il changelog</a> copre cosa esiste per la metà di raccolta.</p> <h2>Dove smette di essere sufficiente Keep a Changelog?</h2> <p>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.</p> <p>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 <a href="https://changeloop.dev/changelog-examples">esempi di changelog</a> raccoglie pagine pubbliche di changelog piuttosto che file di repository. Come trasformare quelle voci in qualcosa a cui la gente torna è trattato in <a href="https://changeloop.dev/blog/it/changelog-page/">come costruire una pagina di changelog</a>.</p> <p>Adottate comunque la specifica. Costa un pomeriggio, rende trattabile il secondo problema, ed è ancora la migliore pagina mai scritta su questo argomento.</p> <h2>FAQ</h2> <p><strong>Keep a Changelog è uno standard?</strong> È 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à.</p> <p><strong>Cosa va nella sezione Unreleased?</strong> 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.</p> <p><strong>Un changelog dovrebbe usare il versionamento semantico?</strong> 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.</p> <p><strong>Le correzioni di sicurezza dovrebbero essere nel changelog prima di essere pubbliche?</strong> 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 è.</p> </article> <article> <h1>Buone pratiche per le release notes che meritano</h1> <p>Fri, 28 Aug 2026 00:00:00 GMT</p> <p>Le buone pratiche per le release notes che contano sono quelle con una conseguenza attaccata: scrivi la voce al momento del merge, nomina chi è interessato, dichiara l'azione richiesta anche quando è nessuna, dai una data ai cambiamenti che rompono qualcosa, mantieni una voce permanente per cambiamento, raggruppa per risultato, e mantieni la sezione noiosa. Ciascuna cambia cosa fa il lettore. La maggior parte del resto dei consigli su questo tema cambia come appaiono le note.</p> <p>Cerca buone pratiche per le release notes e ottieni consigli di stile: sii chiaro, sii conciso, usa un linguaggio semplice, aggiungi screenshot. Niente di tutto questo è sbagliato e niente cambia qualcosa, perché nessun team si è mai seduto con l'intenzione di essere poco chiaro. Le pratiche qui sotto sono accompagnate da quanto costa saltarle, perché una pratica senza una modalità di fallimento allegata è solo una preferenza.</p> <table> <thead> <tr> <th>Pratica</th> <th>Cosa costa saltarla</th> </tr> </thead> <tbody><tr> <td>Scrivere la voce al merge, non al rilascio</td> <td>Le voci ricostruite dopo dicono "vari miglioramenti"</td> </tr> <tr> <td>Nominare chi è interessato</td> <td>Ogni lettore decide che non lo riguarda</td> </tr> <tr> <td>Dichiarare l'azione richiesta, incluso "nessuna"</td> <td>Quaranta ticket di supporto identici, e lettori che presumono il peggio</td> </tr> <tr> <td>Datare i cambiamenti che rompono qualcosa, non versionarli</td> <td>La scadenza si scopre dopo che è passata</td> </tr> <tr> <td>Una voce permanente e collegabile per cambiamento</td> <td>Nessuno può rispondere "quando è cambiato questo"</td> </tr> <tr> <td>Raggruppare per risultato, non per sistema</td> <td>I lettori hanno bisogno della vostra architettura per trovare la loro sezione</td> </tr> <tr> <td>Mantenere la sezione noiosa</td> <td>Sicurezza, compliance e chi debugga una versione perdono la loro fonte</td> </tr> </tbody></table> <h2>Quali sono le buone pratiche per le release notes?</h2> <p><strong>Scrivi la voce quando fai il merge, non quando rilasci.</strong> Costo di saltarlo: chi ricostruisce il rilascio dalla cronologia dei commit non è chi ha fatto il cambiamento, e indovinerà l'intento. Le voci scritte due settimane dopo sono quelle che dicono "vari miglioramenti".</p> <p><strong>Di' chi è interessato, per nome.</strong> "Team sul piano Business", "chiunque usi l'API di export v1", "installazioni self-hosted su Postgres 14". Costo di saltarlo: ogni lettore deve capire se lo riguarda, e la maggior parte deciderà di no.</p> <p><strong>Dichiara l'azione richiesta, incluso quando è nessuna.</strong> Costo di saltarlo: il supporto risponde alla stessa domanda quaranta volte, e i lettori che non hanno chiesto presumono che sia richiesto qualcosa e lo rimandano.</p> <p><strong>Dai una data ai cambiamenti che rompono qualcosa, non un numero di versione.</strong> "Rimosso in v5" non significa nulla per chi non sa quando arriva v5. "Smette di funzionare il 1° novembre" è una data che può segnare in calendario. Costo di saltarlo: la scadenza si scopre dopo che è passata. Cosa conta come tale, e la checklist per pubblicarlo, sono in <a href="https://changeloop.dev/blog/it/breaking-changes/">cos'è un cambiamento che rompe qualcosa</a>.</p> <p><strong>Mantieni una voce permanente e collegabile per cambiamento.</strong> Un'email non è un archivio e un messaggio Slack non è un riferimento. Costo di saltarlo: nessuno può rispondere "quando è cambiato questo" sei mesi dopo, nemmeno voi. L'email ha comunque un compito, trattato nel <a href="https://changeloop.dev/blog/it/product-update-email/">template email di aggiornamento prodotto</a>; rimanda alla voce invece di sostituirla.</p> <p><strong>Raggruppa per risultato, non per sistema.</strong> Costo di saltarlo: il lettore deve tenere la vostra architettura in testa per capire quale sezione gli interessa. L'ordine che segue da questo è in <a href="https://changeloop.dev/blog/it/how-to-write-release-notes/">come scrivere release notes</a>.</p> <p><strong>Mantieni la sezione noiosa.</strong> Aggiornamenti di dipendenze e cambiamenti interni restano, in fondo, una riga ciascuno. Costo di saltarlo: il team di sicurezza, chi revisiona la compliance e chi debugga un disallineamento di versione perdono la loro unica fonte. Le voci che sbagliano più spesso sono le correzioni; <a href="https://changeloop.dev/blog/it/bug-fix-release-notes/">release notes per le correzioni di bug</a> mostra come scriverle perché il lettore sappia se deve agire.</p> <h2>Quali sono le buone pratiche per il changelog, e come si differenziano?</h2> <p>Un changelog è un riferimento, quindi le sue pratiche riguardano completezza e struttura piuttosto che persuasione. Le quattro che contano:</p> <ul> <li><strong>Un tipo di voce fisso per riga.</strong> Added, Changed, Deprecated, Removed, Fixed, Security. Non è uno stile di casa, è un filtro: è ciò che permette di chiedere "solo i cambiamenti che rompono qualcosa". La convenzione <a href="https://changeloop.dev/blog/it/keep-a-changelog-implemented/">Keep a Changelog</a> è la fonte abituale.</li> <li><strong>Una sezione non rilasciata.</strong> Dove vivono le voci tra il merge e il rilascio. La sua assenza è il motivo per cui i team scrivono voci in ritardo.</li> <li><strong>Date ISO.</strong> <code>2026-08-28</code>, non <code>28/08/26</code>, che significa due giorni diversi a seconda del lettore.</li> <li><strong>Una voce per cambiamento, non per commit.</strong> Tre commit che correggono un bug sono una voce.</li> </ul> <p>I due artefatti sono confrontati a fondo in <a href="https://changeloop.dev/blog/it/changelog-vs-release-notes/">changelog vs release notes</a>; la versione breve è che le pratiche del changelog proteggono la completezza e quelle delle release notes proteggono l'attenzione. <a href="https://changeloop.dev/blog/it/private-release-notes-enterprise/">Release notes private per clienti enterprise</a> copre una versione di questo che compare solo quando le vostre clienti non sono più tutte sulla stessa build: gli stessi obiettivi di completezza e attenzione, ma calibrati per account invece che trasmessi a tutte insieme.</p> <h2>Tre che sono puro culto della forma</h2> <p><strong>Emoji come tipi di voce.</strong> Un razzo e una chiave inglese non sono una tassonomia. Sembrano ordinati e non si possono filtrare, ordinare, o leggere da uno screen reader in modo utile. Usa parole, e se vuoi l'emoji, mettila dopo la parola.</p> <p><strong>Numeri di versione semantica come titoli per un prodotto ospitato.</strong> Semver è una promessa sulla compatibilità API. Per un prodotto SaaS dove nessuno sceglie la propria versione, un numero di versione nel titolo è archiviazione interna travestita da notizia. Tieni semver nel changelog e fuori dall'annuncio.</p> <p><strong>Pubblicare secondo un calendario indipendentemente dal contenuto.</strong> Note mensili senza nulla dentro insegnano alla gente che le vostre note sono rumore. Pubblicate quando c'è qualcosa da dire. Il changelog copre il resto.</p> <h2>Quella che è davvero difficile</h2> <p>Mantenere il changelog e l'annuncio sincronizzati, senza scrivere tutto due volte.</p> <p>La maggior parte dei team inizia con una sola pagina, la divide quando le audience divergono, e poi lascia silenziosamente marcire una delle due, di solito il changelog, perché è quello senza una scadenza attaccata. La via d'uscita è strutturale piuttosto che disciplinare: tieni le voci come dati con un tipo, una data e un'audience, e tratta entrambe le superfici come rendering di quello. La nostra rassegna <a href="https://changeloop.dev/changelog-tools">strumenti per il changelog</a> copre cosa è disponibile per questo, inclusi gli strumenti con cui competiamo, e la pagina <a href="https://changeloop.dev/beamer-alternative">alternativa a Beamer</a> è il confronto onesto contro il widget da cui parte la maggior parte dei team.</p> <p>La <a href="https://changeloop.dev/release-notes-template">release notes template</a> è dove vive il passaggio di selezione una volta che le voci esistono.</p> <h2>Se adotti una sola cosa</h2> <p>Scrivi la voce al momento del merge, in un formato fisso, con un tipo. Ogni altra pratica in questa pagina diventa più facile una volta che quella è in atto, e nessuna sopravvive senza di essa.</p> <h2>FAQ</h2> <p><strong>Le release notes dovrebbero avere screenshot?</strong> Solo di ciò che è cambiato, in uso. Uno screenshot di una pagina impostazioni che nessuno ha mai visitato aggiunge scroll, non informazione. Un testo che nomina il risultato e il lettore interessato batte un'immagine che non mostra nessuno dei due.</p> <p><strong>Come si scrivono release notes per un cambiamento che rompe qualcosa?</strong> Prima la data, secondo i chiamanti interessati, terza l'azione richiesta, quarta la migrazione. Mai iniziare con il numero di versione. La forma completa, con una voce di esempio, è in <a href="https://changeloop.dev/blog/it/breaking-changes/">cos'è un cambiamento che rompe qualcosa</a>.</p> <p><strong>Le release notes dovrebbero essere scritte da ingegneria o marketing?</strong> Redatte dall'ingegnere che ha fatto il cambiamento, al momento del merge, ed editate da qualcuno che le legge come uno sconosciuto. Nessuno dei due da solo produce note su cui un cliente possa agire.</p> <p><strong>Qual è il formato ideale per le release notes?</strong> Prima gli elementi con scadenza, poi le nuove capacità, poi i miglioramenti, poi una lista di una riga ciascuna col resto. La <a href="https://changeloop.dev/release-notes-template">release notes template</a> è quel formato come pagina da compilare.</p> </article> </main></body></html>