Aggiunta di informazioni sulle modifiche per le note di rilascio¶

Molti strumenti di BeeWare usano towncrier per aiutare a costruire le note di rilascio per ogni release. Quando si invia una richiesta di pull a uno degli strumenti applicabili, questa dovrà includere una nota di modifica; questa nota di modifica diventerà la voce nelle note di rilascio che descriverà la modifica apportata.

Ogni richiesta di pull deve includere almeno un file nella cartella changes/ che fornisca una breve descrizione della modifica implementata dalla richiesta di pull. La nota di modifica deve essere in formato Markdown, in un file dal nome <id>.<tipo di frammento>.md. Se la modifica proposta risolve un bug o implementa una funzionalità per la quale esiste un numero di problema esistente, l'ID sarà il numero di quel ticket. Se la modifica non ha un problema corrispondente, il numero di PR può essere usato come ID. Non si conosce il numero di PR finché non si invia la richiesta di pull, quindi il primo passaggio di CI non supererà il controllo towncrier; aggiungendo la nota di modifica e inviando un aggiornamento della PR, il CI dovrebbe passare.

Esistono cinque tipi di frammenti:

caratteristica: La PR aggiunge un nuovo comportamento o una capacità che non era possibile in precedenza (ad esempio, l'aggiunta del supporto per un nuovo formato di pacchettizzazione o una nuova funzionalità in un formato di pacchettizzazione esistente);
bugfix: La PR corregge un bug nell'implementazione esistente;
doc: Il PR rappresenta un miglioramento significativo della documentazione;
La PR rappresenta una modifica incompatibile con le versioni precedenti dell'API {{ nome_formale }}. API; oppure
misc; Una modifica minore o amministrativa (ad esempio, la correzione di un errore di battitura, un chiarimento linguistico minore o l'aggiornamento della versione di una dipendenza) che non deve essere annunciata nelle note di rilascio.

Questa descrizione nella nota di modifica dovrebbe essere un riassunto di alto livello "marketing" della modifica dal punto di vista dell'utente, non una descrizione tecnica approfondita o un dettaglio di implementazione. Si distingue da un messaggio di commit: un messaggio di commit descrive ciò che è stato fatto in modo che i futuri sviluppatori possano seguire il ragionamento per una modifica; la nota di modifica è una descrizione a beneficio degli utenti, che potrebbero non avere conoscenze interne.

Ad esempio, se si risolve un bug relativo alla denominazione del progetto, il messaggio di commit potrebbe essere il seguente:

Applicare un controllo di espressione regolare più forte per escludere i nomi di progetto che iniziano con cifre.

La nota di modifica corrispondente sarebbe qualcosa di simile:

I nomi dei progetti non possono più iniziare con un numero.

Alcune PR introducono più funzionalità e correggono più bug, oppure introducono più modifiche incompatibili con il passato. In questo caso, la PR può avere più file di note di modifica. Se è necessario associare due tipi di frammenti allo stesso ID, è possibile aggiungere un suffisso numerico. Ad esempio, se la PR 789 ha aggiunto una funzionalità descritta dal ticket 123, ha chiuso un bug descritto dal ticket 234 e ha apportato due modifiche incompatibili, si potrebbero avere 4 file di note di modifica:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

Per maggiori informazioni su towncrier e sui tipi di frammenti, vedere News Fragments. È anche possibile vedere esempi esistenti di frammenti di notizie nella cartella changes del repository {{ nome_formale }}. Se questa cartella è vuota, è probabile che sia perché {{ nome_formale }} ha recentemente pubblicato un nuovo rilascio; i file delle note di modifica vengono cancellati e combinati per aggiornare le note di rilascio a ogni rilascio. Si può guardare a quel file per vedere lo stile di commento richiesto; si può guardare a recent merged PRs per vedere come formattare le note di modifica.