Note di rilascio: cosa cambia per chi usa il programma
Di Redazione Quaderno dei Sistemi
Distingui novità, correzioni, incompatibilità e azioni richieste. Una traccia di note di rilascio leggibile anche senza conoscere il codice.
Le note di rilascio spiegano l’effetto di una nuova versione per chi la utilizza. Un elenco di modifiche al codice non risponde sempre a questa domanda. Su GitHub una release può raccogliere software, note e file scaricabili; il testo editoriale deve rendere chiaro a quale pacchetto si riferisce.
Ordinare per conseguenza
Dividi la nota in novità, correzioni e azioni richieste. Scrivi «l’esportazione mantiene le intestazioni delle colonne» invece di «migliorato il modulo export». La prima frase indica un comportamento osservabile. Se una funzione cambia formato, metti l’avviso prima dei miglioramenti minori.
Collegare versione e prova
Inserisci l’identificativo esatto della versione e un riferimento alla verifica svolta. Non affermare «tutti i problemi risolti» se hai controllato solo un caso. Un esempio redazionale: «verificata l’esportazione del file campione con tre colonne» chiarisce l’ampiezza della prova senza trasformarla in una garanzia generale.
Spiegare l’aggiornamento
Se l’utente deve fare qualcosa, separa i passi dal resto della nota. Indica quali dati conservare e dove trovare le istruzioni specifiche. Non inventare una procedura di ripristino: descrivila soltanto se il progetto la supporta e se è stata verificata.
Prima della pubblicazione, confronta titolo, nome del pacchetto e numero riportato nel programma. Una nota corretta associata al file sbagliato è comunque un problema. Mantieni infine accessibili le note precedenti, così chi aggiorna dopo molto tempo può ricostruire i cambiamenti.