Änderungsinformationen für Versionshinweise hinzufügen

Viele BeeWare-Werkzeuge verwenden towncrier, um bei der Erstellung der Versionshinweise für jede Version zu helfen. Wenn Sie eine Pull-Anfrage an eines der entsprechenden Werkzeuge senden, muss diese eine Änderungsnotiz enthalten - diese Änderungsnotiz wird der Eintrag in den Versionshinweisen, der die vorgenommene Änderung beschreibt.

Jeder Pull Request muss mindestens eine Datei im Verzeichnis changes/ enthalten, die eine kurze Beschreibung der durch den Pull Request implementierten Änderung enthält. Die Änderungsnotiz sollte im Markdown-Format sein, in einer Datei, die den Namen <id>.<Fragmenttyp>.md hat. Wenn die Änderung, die Sie vorschlagen, einen Fehler behebt oder eine Funktion implementiert, für die es bereits eine Ticketnummer gibt, ist die ID die Nummer dieses Tickets. Wenn die Änderung kein entsprechendes Ticket hat, kann die PR-Nummer als ID verwendet werden. Sie werden diese PR-Nummer nicht kennen, bis Sie den Pull-Request veröffentlichen, so dass der erste CI-Durchlauf die `towncrier'-Prüfung nicht bestehen wird; fügen Sie die Änderungsnotiz hinzu und veröffentlichen Sie ein PR-Update und CI sollte dann bestehen.

Es gibt fünf Fragmenttypen:

• Funktion": Der PR fügt ein neues Verhalten oder eine Fähigkeit hinzu, die vorher nicht möglich war (z.B. Unterstützung für ein neues Verpackungsformat oder eine neue Funktion in einem bestehenden Verpackungsformat);
• Fehlerbehebung": Der PR behebt einen Fehler in der bestehenden Implementierung;
• doc: Der PR ist eine wesentliche Verbesserung der Dokumentation;
• Entfernung; Der PR stellt eine rückwärts inkompatible Änderung der BeeWare API; oder
• misc; Eine geringfügige oder administrative Änderung (z.B. das Beheben eines Tippfehlers, eine geringfügige sprachliche Klarstellung oder die Aktualisierung einer Abhängigkeitsversion), die nicht in den Versionshinweisen angekündigt werden muss.

Diese Beschreibung in der Änderungsnotiz sollte eine hochrangige "Marketing"-Zusammenfassung der Änderung aus der Sicht des Benutzers sein, keine tiefgehende technische Beschreibung oder Implementierungsdetails. Sie unterscheidet sich von einer Commit-Nachricht - eine Commit-Nachricht beschreibt, was getan wurde, so dass zukünftige Entwickler die Gründe für eine Änderung nachvollziehen können; die Änderungsnotiz ist eine Beschreibung zum Nutzen der Benutzer, die möglicherweise keine Kenntnisse über Interna haben.

Wenn Sie zum Beispiel einen Fehler im Zusammenhang mit der Projektbenennung beheben, könnte die Commit-Nachricht lauten:

Wenden Sie eine stärkere Prüfung auf reguläre Ausdrücke an, um Projektnamen, die mit Ziffern beginnen, zu verbieten.

Der entsprechende Änderungsvermerk würde etwa so lauten:

Projektnamen können nicht mehr mit einer Nummer beginnen.

Einige PRs führen mehrere Funktionen ein und beheben mehrere Fehler oder führen mehrere rückwärtskompatible Änderungen ein. In diesem Fall kann der PR mehrere Änderungsnotizdateien haben. Wenn Sie zwei Fragmenttypen mit der gleichen ID verknüpfen müssen, können Sie ein numerisches Suffix anhängen. Wenn z.B. PR 789 eine Funktion hinzugefügt hat, die in Ticket 123 beschrieben wurde, einen Fehler geschlossen hat, der in Ticket 234 beschrieben wurde, und außerdem zwei rückwärts inkompatible Änderungen vorgenommen hat, könnten Sie 4 Änderungsnotizdateien haben:

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

Für weitere Informationen über towncrier und Fragmenttypen siehe News Fragments. Sie können auch bestehende Beispiele von Nachrichtenfragmenten im Verzeichnis changes des BeeWare Repositorys sehen. Wenn dieser Ordner leer ist, liegt das wahrscheinlich daran, dass BeeWare vor kurzem eine neue Version veröffentlicht hat; Änderungsnotizdateien werden gelöscht und kombiniert, um die release notes mit jeder Version zu aktualisieren. Sie können sich diese Datei ansehen, um zu sehen, welche Art von Kommentar erforderlich ist; Sie können sich recently merged PRs ansehen, um zu sehen, wie Sie Ihre Änderungsnotizen formatieren sollten.