Ajout d'informations sur les modifications pour les notes de mise à jour

De nombreux outils BeeWare utilisent towncrier pour aider à la construction des notes de version pour chaque version. Lorsque vous soumettez une demande d'extraction à l'un des outils applicables, elle devra inclure une note de changement - cette note de changement deviendra l'entrée dans les notes de publication décrivant le changement qui a été fait.

Chaque demande d'extraction doit inclure au moins un fichier dans le répertoire changes/ qui fournit une courte description du changement implémenté par la demande d'extraction. La note de changement doit être au format Markdown, dans un fichier dont le nom est du format <id>.<fragment type>.md. Si le changement que vous proposez corrige un bogue ou implémente une fonctionnalité pour laquelle il existe un numéro de problème, l'ID sera le numéro de ce ticket. Si le changement n'a pas de problème correspondant, le numéro de PR peut être utilisé comme identifiant. Vous ne connaîtrez pas ce numéro de PR tant que vous n'aurez pas poussé la pull request, donc le premier passage du CI échouera la vérification towncrier ; ajoutez la note de changement et poussez une mise à jour du PR et le CI devrait alors passer.

Il existe cinq types de fragments :

• feature : Le PR ajoute un nouveau comportement ou une nouvelle capacité qui n'était pas possible auparavant (par exemple, en ajoutant le support d'un nouveau format d'emballage, ou une nouvelle fonctionnalité dans un format d'emballage existant) ;
• bugfix : Le PR corrige un bogue dans l'implémentation existante ;
• doc : Le PR est une amélioration significative de la documentation ;
• removal ; The PR represents a backward incompatible change in BeeWare API ; or the PR represents a backward incompatible change in BeeWare API. API ; ou
• misc ; Un changement mineur ou administratif (par exemple, la correction d'une coquille, une clarification linguistique mineure, ou la mise à jour d'une version de dépendance) qui n'a pas besoin d'être annoncé dans les notes de publication.

Cette description dans la note de modification doit être un résumé "marketing" de haut niveau de la modification du point de vue de l'utilisateur, et non une description technique approfondie ou un détail d'implémentation. Elle se distingue d'un message de validation - un message de validation décrit ce qui a été fait afin que les futurs développeurs puissent suivre le raisonnement d'un changement ; la note de modification est une description à l'intention des utilisateurs, qui peuvent ne pas avoir connaissance des éléments internes.

Par exemple, si vous corrigez un bogue lié à la dénomination d'un projet, le message de validation pourrait être le suivant :

Appliquer une vérification d'expression régulière plus forte pour interdire les noms de projets qui commencent par des chiffres.

La note de modification correspondante se lirait comme suit :

Les noms de projets ne peuvent plus commencer par un chiffre.

Certains PR introduisent plusieurs fonctionnalités et corrigent plusieurs bogues, ou introduisent plusieurs changements incompatibles avec le passé. Dans ce cas, la PR peut avoir plusieurs fichiers de notes de modification. Si vous devez associer deux types de fragments au même identifiant, vous pouvez ajouter un suffixe numérique. Par exemple, si la PR 789 a ajouté une fonctionnalité décrite par le ticket 123, a corrigé un bug décrit par le ticket 234, et a également apporté deux changements incompatibles, vous pouvez avoir 4 fichiers de notes de changement :

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

Pour plus d'informations sur towncrier et les types de fragments, voir News Fragments. Vous pouvez également voir des exemples existants de fragments de nouvelles dans le répertoire changes du référentiel BeeWare. Si ce répertoire est vide, c'est probablement parce que BeeWare a récemment publié une nouvelle version ; les fichiers de notes de changement sont supprimés et combinés pour mettre à jour les notes de publication à chaque publication. Vous pouvez consulter ce fichier pour voir le style de commentaire requis ; vous pouvez consulter PRs récemment fusionnés pour voir comment formater vos notes de modification.