Tilføjelse af ændringsoplysninger til release notes

Mange BeeWare-værktøjer bruger towncrier til at hjælpe med at oprette release notes for hver udgivelse. Når du indsender en pull request til et af de relevante værktøjer, skal den indeholde en ændringsnote - denne ændringsnote bliver en post i release notes, der beskriver den ændring, der er foretaget.

Hver pull-anmodning skal indeholde mindst én fil i changes/ -mappen, der indeholder en kort beskrivelse af den ændring, der implementeres med pull-anmodningen. Ændringsnotatet skal være i Markdown-format i en fil med navnet <id>.<fragment type>.md. Hvis den ændring, du foreslår, vil rette en fejl eller implementere en funktion, for hvilken der findes et eksisterende problemnummer, vil ID'et være nummeret på den pågældende billet. Hvis ændringen ikke har noget tilsvarende problem, kan PR-nummeret bruges som ID. Du kender ikke dette PR-nummer, før du har sendt pull-anmodningen, så den første CI-test vil fejle towncrier -kontrollen. Tilføj ændringsnoten, send en PR-opdatering, og CI bør derefter bestå.

Der er fem fragmenttyper:

• feature: PR tilføjer en ny funktion eller mulighed, der ikke tidligere var mulig (f.eks. tilføjelse af support til et nyt pakkeformat eller en ny funktion i et eksisterende pakkeformat).
• bugfix: PR retter en fejl i den eksisterende implementering.
• doc: PR er en væsentlig forbedring af dokumentationen.
• removal; PR repræsenterer en bagudkompatibel ændring i BeeWare API; eller
• misc; En mindre eller administrativ ændring (f.eks. rettelse af en stavefejl, en mindre sproglig præcisering eller opdatering af en afhængighedsversion), der ikke behøver at blive annonceret i release notes.

Denne beskrivelse i ændringsnotatet skal være en overordnet "markedsføringsmæssig" sammenfatning af ændringen set fra brugerens perspektiv, ikke en dybdegående teknisk beskrivelse eller implementeringsdetaljer. Den adskiller sig fra en commit-besked – en commit-besked beskriver, hvad der er blevet gjort, så fremtidige udviklere kan følge begrundelsen for en ændring; ændringsnotatet er en beskrivelse til gavn for brugerne, som muligvis ikke har kendskab til de interne forhold.

Hvis du f.eks. retter en fejl relateret til projektnavngivning, kan commit-meddelelsen lyde således:

Anvend en strengere regulær udtryk-kontrol for at forhindre projektnavne, der begynder med cifre.

Den tilsvarende ændringsnote ville lyde nogenlunde således:

Projektnavne kan ikke længere begynde med et tal.

Nogle PR'er introducerer flere funktioner og retter flere fejl eller introducerer flere bagudkompatible ændringer. I så fald kan PR'en have flere ændringsnotatfiler. Hvis du har brug for at knytte to fragmenttyper til samme ID, kan du tilføje et numerisk suffiks. Hvis PR 789 f.eks. tilføjede en funktion beskrevet i billet 123, lukkede en fejl beskrevet i billet 234 og også foretog to bagudkompatible ændringer, kan du have 4 ændringsnotatfiler:

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

For mere information om towncrier og fragmenttyper, se Nyhedsfragmenter. Du kan også se eksisterende eksempler på nyhedsfragmenter i changes mappen i BeeWare repositoryet. Hvis denne mappe er tom, skyldes det sandsynligvis, at BeeWare for nylig har udgivet en ny version; ændringsnotatfiler slettes og kombineres for at opdatere release notes med hver udgivelse. Du kan se den fil for at se, hvilken stil der kræves for kommentarer. Du kan se nylig sammenlagte PR'er for at se, hvordan du formaterer dine ændringsnoter.