Esempi di changelog

1. Un rilascio SaaS ordinario

Il caso comune: una manciata di cambiamenti visibili all'utente, nessuna migrazione, nessun dramma. È breve perché il rilascio era piccolo, e resistere alla tentazione di riempirlo è gran parte del mestiere.

## 20 agosto 2026

### Novità
- Viste salvate nella casella. Fissa un filtro una volta e riutilizzalo
  dalla barra laterale.

### Migliorie
- Il job di esportazione ora segnala l'avanzamento invece di sembrare
  bloccato sugli account grandi.

### Correzioni
- I membri invitati non vedono più una dashboard vuota prima del
  primo accesso.

2. Un rilascio API con una deprecazione

Chi legge un changelog API cerca una cosa sola: se la propria integrazione sta per rompersi e quanto tempo ha. Mettilo in cima e dagli una data.

## Acme API 4.2 - 20 agosto 2026

### Cambiamenti importanti
- `?page=` viene rimosso su tutti gli endpoint di elenco. Usa il valore
  `nextCursor` della risposta precedente.
  `?page=` restituirà 400 dopo il 1° ottobre 2026.
  Passaggi di migrazione: acme.example/docs/pagination

### Novità
- I webhook possono essere limitati a un singolo progetto.

### Migliorie
- Gli endpoint di elenco rispondono circa quattro volte più velocemente
  sugli account con oltre 10.000 record.

3. Un rilascio mobile

Gli app store mostrano un campo di novità troncato, e la revisione può trattenere una build per giorni. Entrambi i fatti plasmano la voce.

## iOS 3.4.0 - 20 agosto 2026

Modalità offline. Apri, leggi e scrivi senza connessione;
tutto si sincronizza quando torni online.

### Anche in questo rilascio
- Avvio più veloce sui dispositivi più vecchi.
- Corretto un crash all'apertura di un link condiviso da Mail.

4. Una correzione di sicurezza

L'unica voce in cui dire meno è corretto. Gli utenti devono sapere che devono aggiornare; nessun altro ha bisogno di una descrizione abbastanza precisa da attaccare la versione che non ha ancora aggiornato.

## 20 agosto 2026

### Sicurezza
- Rafforzata la convalida dei token di sessione. Gli account su
  installazioni autogestite dovrebbero aggiornare alla 4.2.1 o
  successiva. Segnalato responsabilmente; nessuna prova di sfruttamento.
  Dettagli: acme.example/security/2026-08

5. Com'è fatta una voce cattiva

Ogni riga qui ha una forma reale, e ogni riga è un errore:

## v2.3.7

- Unita la PR #482 da feature/inbox-refactor
- Bump di lodash da 4.17.20 a 4.17.21
- Corretta race condition in MembershipCache.resolve()
- Varie correzioni e migliorie
- Refactoring del modello SavedView (grazie, Dave!)

Cosa hanno in comune quelle buone

• Descrivono un risultato, non un'implementazione. Chi non ha mai visto il codice può comunque capire se la voce lo riguarda.
• Omettono cose. Aggiornamenti di dipendenze, refactor, cambiamenti di CI e rinomine interne sono assenti, e proprio questa assenza mantiene leggibile il resto.
• Mettono per prima la cosa costosa. Se qualcosa si rompe, è la prima intestazione, con una data.
• Sono datate in un modo utile a chi legge: un numero di versione dove gli utenti vedono le versioni, una data dove non possono.
• Sono noiose di proposito. Niente punti esclamativi, niente aggettivi da marketing, niente «siamo felici di annunciare». Chi legge un changelog cerca informazioni e si irrita per qualsiasi cosa che ostacoli.

Domande frequenti

Che formato dovrebbe usare un changelog?

keepachangelog.com è la cosa più vicina a uno standard, e i nomi delle sue sezioni (Added, Changed, Deprecated, Removed, Fixed, Security) sono ampiamente riconosciuti. Conta molto meno del testo dentro le sezioni. Un formato coerente con voci vaghe è peggio di un formato libero con voci precise.

Con che frequenza dovremmo pubblicare?

Con il ritmo che si adatta ai tuoi rilasci, e con costanza. Pubblicare per ogni rilascio è la regola più semplice. Accorpare un mese di rilasci in un solo post rende ogni singolo cambiamento più difficile da trovare dopo, che è proprio quando la maggior parte delle persone legge davvero un changelog.

Il changelog dovrebbe stare sul nostro sito o su una pagina di terzi?

Sul tuo sito se puoi, perché è lì che si accumulano il traffico e il valore di ricerca, e perché un changelog su un dominio altrui è a un link dal tuo prodotto invece di farne parte. È questo l'argomento a favore di servirlo come feed che renderizzi tu, invece che come pagina ospitata da collegare.

Le persone leggono davvero i changelog?

Una piccola parte li legge regolarmente e una parte molto più grande li cerca nel momento in cui qualcosa cambia sotto di loro. Quel secondo gruppo è il motivo per scrivere il sintomo invece della causa: cercano ciò che è successo a loro, con le loro parole.

Per continuare a leggere: Changelog vs release notes: qual è la differenza? e Keep a Changelog, davvero implementato.