Inizia con un modello orientato all’utente
Sostituisci ogni campo tra parentesi quadre con informazioni verificate. Rimuovi le sezioni irrilevanti invece di inventare funzionalità. Se non occorre alcuna azione per aggiornare, dichiaralo esplicitamente dopo aver verificato il percorso di aggiornamento supportato.
# [Versione] — [Data di rilascio]
## Novità principali
- [Miglioramento visibile all’utente e chi ne beneficia]
## Aggiornamento
- Da: [versione precedente supportata]
- Azione: [migrazione necessaria o nessuna azione richiesta]
- Verifica: [come confermare un aggiornamento riuscito]
## Modifiche incompatibili
- [Comportamento modificato, utenti interessati e link alla migrazione]
## Correzioni
- [Problema risolto e link alla issue o pull request]
## Problemi noti
- [Limitazione restante e soluzione alternativa]
## Collaboratori
[Ringrazia i collaboratori e collega il registro completo delle modifiche]Trasforma le note generate in una spiegazione leggibile
GitHub può generare note contenenti pull request integrate, collaboratori e un link al registro completo delle modifiche. Considera questo risultato una bozza. Verifica i confini della versione, rimuovi le voci irrilevanti e raggruppa le modifiche per le attività svolte dai tuoi utenti.
Per esempio, “Correggere un caso limite del parser” offre poche indicazioni. Se è corretto, spiega che ora i file CSV con l’ultima colonna vuota vengono importati correttamente e collega la correzione per i dettagli tecnici. Non affermare che ogni problema di parsing è risolto se è cambiato un solo caso.
Rivedi il percorso di aggiornamento prima dell’annuncio
Prova l’aggiornamento documentato da una versione precedente supportata. Controlla i link di download e assicurati che la documentazione corrisponda alla versione. Distingui un’anteprima da una versione stabile e rendi facili da trovare le limitazioni rimanenti.
Pubblica le informazioni sulla versione prima di collegarle da un post della community. Usa l’annuncio per evidenziare un miglioramento significativo, mantenendo le note di rilascio come riferimento dettagliato. Raccogli le domande successive e chiarisci le istruzioni quando necessario.
Domande frequenti
Le note di rilascio sono la stessa cosa di un registro delle modifiche?
Si sovrappongono. Un registro delle modifiche documenta i cambiamenti nel tempo; le note di rilascio spiegano una versione specifica e il suo effetto sugli utenti. Collegali per consentire ai lettori di passare dalla panoramica ai dettagli.
Posso pubblicare le note generate automaticamente senza modificarle?
Rivedile prima. I titoli delle pull request generati possono omettere passaggi di migrazione, impatto sugli utenti o problemi noti.
Ogni piccola modifica al codice dovrebbe comparire tra le novità principali?
No. Riserva le novità principali ai cambiamenti importanti per gli utenti e mantieni la cronologia tecnica dettagliata nel registro delle modifiche collegato.