Una voce del changelog descrive una modifica confermata: versione, data effettiva, utenti coinvolti, comportamento precedente e nuovo e azione necessaria. Il modello riguarda una funzione già distribuita, non il primo lancio.
Raccogliere i fatti di una modifica
Conferma con il responsabile nome della funzione, identificativo della versione, momento reale del rilascio e utenti coinvolti. Una data prevista non è una data effettiva. Per un accesso limitato indica il gruppo.
Il ticket interno aiuta a ricostruire le decisioni ma non sostituisce una descrizione per i clienti. Il testo deve essere comprensibile senza note interne.
Registrare versione e data
Usa l'identificativo adottato dal prodotto, senza inventare un numero per l'articolo. Se utilizza SemVer, interpreta i componenti secondo le regole e l'API pubblica dichiarata. Altri sistemi possono esprimere significati diversi.
Scrivi una data inequivocabile, per esempio YYYY-MM-DD, e il fuso se l'ora è importante. La data di scrittura può differire. Per un rilascio graduale specifica inizio e copertura attuale.
Descrivere prima e dopo
Spiega il comportamento osservabile prima e dopo, chi è coinvolto, i limiti e i passi richiesti. Se non occorre un'azione, dichiaralo.
Non promettere vantaggi non verificati. Un nuovo filtro non dimostra più vendite o un certo risparmio di tempo. Prezzi e fatturazione restano nella documentazione pertinente.
Esempio di una voce
L'esempio è fittizio e non descrive un rilascio di Semly.
- Funzione: filtrare un elenco di documenti.
- Versione: 2.4.1 secondo la numerazione del prodotto illustrativo.
- Data effettiva: 2026-10-12.
- Prima: il secondo filtro rimuoveva il primo.
- Dopo: l'elenco applica entrambi i filtri selezionati.
- Ambito: utenti dell'elenco nella versione 2.4.1.
- Azione: aggiornare la vista aperta dopo l'aggiornamento.
- Limite: i modelli di filtro salvati non cambiano.
Il limite evita supposizioni sui modelli. Nel caso reale aggiungi un collegamento verificato alle istruzioni. Se mancano, descrivi il passo senza inventare un URL.
Verificare prima di salvare
Confronta versione, data, copertura e comportamento con il team di prodotto. Controlla l'azione e i collegamenti.
Un lettore senza conoscere il ticket deve capire cosa è cambiato e quando. Funzioni indipendenti hanno voci separate nella versione; la stessa modifica non richiede più articoli.
Conservare il significato nelle traduzioni
Mantieni identificativo, momento, ambito e limiti. Un'altra lingua non conferma accesso in un nuovo mercato.
Quando correggi il testo, conserva la vera data di rilascio e segnala separatamente la correzione editoriale. Non è un nuovo rilascio.
Fonte sulla numerazione
SemVer riguarda un'API pubblica dichiarata. Non è obbligatorio per ogni applicazione SaaS.
