Implementierung einer neuen Funktion

Sobald der Vorschlagsprozess abgeschlossen ist, sollten Sie einen vollständigen Entwurf für eine neue Funktion haben. Das bedeutet, dass es Zeit ist, mit dem Schreiben zu beginnen!

Wenn Ihre Funktion eine plattformspezifische Implementierung erfordert, sollte der Vorschlagsprozess bestätigt haben, dass die Idee auf allen Plattformen implementiert werden kann. Als die Person, die eine neue Funktion zum ersten Mal implementiert, sind Sie jedoch nicht für die Implementierung der neuen Funktion für alle Plattformen verantwortlich. Sie müssen eine vollständige Implementierung für mindestens eine Plattform bereitstellen, einschließlich Tests. Für alle anderen Plattformen müssen Sie eine "Stub"-Implementierung bereitstellen - eine Implementierung, die die bloße Schnittstellendefinition bereitstellt, aber einen NotImplementedError auslöst oder eine Logmeldung ausgibt, dass das Verhalten auf dieser Plattform nicht implementiert ist.

Ein wichtiger Teil der Implementierung einer neuen Funktion ist die Sicherstellung, dass diese Funktion vollständig dokumentiert ist. Dies bedeutet zumindest, dass es eine API-Dokumentation gibt, aber es kann auch erforderlich sein, eine Anleitung oder ein Themenhandbuch hinzuzufügen.

Beitrag zu neuen Funktionen

Entwicklungsumgebung einrichten

Um zu BeeWare beizutragen, müssen Sie eine Entwicklungsumgebung einrichten.

Voraussetzungen

Sie müssen die folgenden Voraussetzungen installieren.

macOSLinuxWindows

BeeWare erfordert Python 3.10+. Sie benötigen auch eine Methode zur Verwaltung virtueller Umgebungen (wie venv).

Sie können die Version von Python, die Sie installiert haben, überprüfen, indem Sie diese ausführen:

Python 3.8.10 (Standardversion, 20. Juli 2020, 16:16:00)

Wenn Sie mehr als eine Version von Python installiert haben, müssen Sie eventuell python3 durch eine bestimmte Versionsnummer ersetzen (z.B. python3.13)

Wir empfehlen, kürzlich veröffentlichte Versionen von Python zu vermeiden (d.h. Versionen, die eine ".0" oder ".1" Mikro-Versionsnummer haben, wie z.B. 3.14.0). Der Grund dafür ist, dass die Werkzeuge, die zur Unterstützung von Python unter macOS benötigt werden, in der Regel nicht für kürzlich veröffentlichte stabile Python-Versionen verfügbar sind.

BeeWare erfordert Python 3.10+. Sie benötigen auch eine Methode zur Verwaltung virtueller Umgebungen (wie venv).

Sie können die Version von Python, die Sie installiert haben, überprüfen, indem Sie diese ausführen:

Python 3.8.10 (Standardversion, 20. Juli 2020, 16:16:00)

Wenn Sie mehr als eine Version von Python installiert haben, müssen Sie eventuell python3 durch eine bestimmte Versionsnummer ersetzen (z.B. python3.13)

Wir empfehlen, kürzlich veröffentlichte Versionen von Python zu vermeiden (d.h. Versionen, die eine ".0" oder ".1" Mikro-Versionsnummer haben, wie z.B. 3.14.0). Der Grund dafür ist, dass die Werkzeuge, die zur Unterstützung von Python unter Linux benötigt werden, oft nicht für kürzlich veröffentlichte stabile Python-Versionen verfügbar sind.

BeeWare erfordert Python 3.10+. Sie benötigen auch eine Methode zur Verwaltung virtueller Umgebungen (wie venv).

Sie können die Version von Python, die Sie installiert haben, überprüfen, indem Sie diese ausführen:

C:\...>py -3 --version

Wenn Sie mehr als eine Version von Python installiert haben, müssen Sie möglicherweise die -3 durch eine bestimmte Versionsnummer ersetzen (z.B. -python3.13)

Wir empfehlen, kürzlich veröffentlichte Versionen von Python zu vermeiden (d.h. Versionen, die eine ".0" oder ".1" Mikro-Versionsnummer haben, wie z.B. 3.14.0). Der Grund dafür ist, dass die Werkzeuge, die zur Unterstützung von Python unter Windows benötigt werden, in der Regel nicht für kürzlich veröffentlichte stabile Python-Versionen verfügbar sind.

Richten Sie Ihre Entwicklungsumgebung ein

Es wird empfohlen, die Entwicklungsumgebung für BeeWare in einer virtuellen Umgebung einzurichten und dann die Entwicklungsversion von BeeWare und seine Abhängigkeiten zu installieren.

Klonen Sie das BeeWare Repository

Gehen Sie als Nächstes zur BeeWare Seite auf GitHub, und, falls noch nicht geschehen, forken Sie das Repository in Ihr eigenes Konto. Klicken Sie anschließend auf die Schaltfläche "<> Code" auf Ihrem Fork. Wenn Sie die GitHub-Desktop-Anwendung auf Ihrem Computer installiert haben, können Sie "Mit GitHub-Desktop öffnen" wählen; andernfalls kopieren Sie die angegebene HTTPS-URL und verwenden sie, um das Repository über die Befehlszeile auf Ihren Computer zu klonen:

macOSLinuxWindows

Forken Sie das BeeWare Repository, und dann:

$ git clone https://github.com/<dein Benutzername>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Forken Sie das BeeWare Repository, und dann:

$ git clone https://github.com/<dein Benutzername>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Forken Sie das BeeWare Repository, und dann:

C:\...>git clone https://github.com/<dein Benutzername>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Ein Upstream-Repository festlegen

Nachdem Sie Ihren Fork geklont haben, fügen Sie das BeeWare-Repository als upstream Remote hinzu. Dadurch erhält Ihr lokaler Klon einen Verweis auf das ursprüngliche Repository, was die Synchronisierung von Updates im Laufe der Zeit erleichtert.

Sie benötigen außerdem Tags aus upstream, damit Tools wie Toga und Briefcase genaue Versionsnummern ermitteln können:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Wenn Sie möchten, dass Ihre Fork diese Tags ebenfalls enthält, können Sie sie pushen:

$ git push --tags

Dies kann nützlich sein, wenn Sie später einen neuen Klon erstellen und möchten, dass Tags aus Ihrem Fork verfügbar sind.

Erstellen einer virtuellen Umgebung

Um eine virtuelle Umgebung einzurichten und pip zu aktualisieren, führen Sie aus:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Ihre Eingabeaufforderung sollte nun ein Präfix (.venv) vorangestellt haben.

Installieren Sie BeeWare

Jetzt, da Sie den Quellcode haben, können Sie eine editierbare Installation von BeeWare in Ihrer Entwicklungsumgebung durchführen. Führen Sie den folgenden Befehl aus:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Pre-Commit aktivieren

BeeWare verwendet ein Tool namens pre-commit, um einfache Probleme zu identifizieren und die Codeformatierung zu standardisieren. Zu diesem Zweck wird ein Git-Hook installiert, der automatisch eine Reihe von Code-Linters ausführt, bevor ein Git-Commit abgeschlossen wird. Um pre-commit zu aktivieren, führen Sie aus:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Jetzt können Sie mit dem Hacken von BeeWare beginnen!

Arbeiten von einem Zweig aus

Bevor Sie mit der Arbeit an Ihrer Änderung beginnen, stellen Sie sicher, dass Sie einen Zweig erstellt haben. Wenn Sie Ihren Repository Fork klonen, werden Sie standardmäßig in Ihrem main-Zweig ausgecheckt. Dies ist eine direkte Kopie des BeeWare's main branch.

Sie können zwar einen Pull Request von Ihrem main einreichen, aber es ist besser, wenn Sie das nicht tun. Wenn Sie einen Pull Request einreichen, der fast richtig ist, kann das Mitglied des Kernteams, das Ihren Pull Request prüft, die notwendigen Änderungen vornehmen, anstatt eine Rückmeldung zu geben, in der um eine kleine Änderung gebeten wird. Wenn Sie jedoch Ihren Pull Request von Ihrem main einreichen, werden die Prüfer daran gehindert Änderungen vorzunehmen.

Von Ihrem Hauptzweig aus zu arbeiten, macht es auch für Sie schwierig, nachdem Sie Ihren ersten Pull Request fertiggestellt haben. Wenn Sie an einem zweiten Pull Request arbeiten wollen, brauchen Sie eine "saubere" Kopie des Hauptzweigs des Upstream-Projekts, auf der Sie Ihren zweiten Beitrag aufbauen können; wenn Sie Ihren ersten Beitrag von Ihrem main gemacht haben, haben Sie diese saubere Version nicht mehr zur Verfügung.

Stattdessen sollten Sie Ihre Änderungen in einem Funktionszweig vornehmen. Ein Funktionszweig hat einen einfachen Namen, um die Änderung zu identifizieren, die Sie vorgenommen haben. Wenn Sie zum Beispiel einen Fehler beheben, der Build-Probleme unter Windows 11 verursacht, könnten Sie einen Feature-Zweig fix-win11-build erstellen. Wenn sich Ihr Fehler auf ein bestimmtes Problem bezieht, das gemeldet wurde, ist es auch üblich, die Nummer des Problems im Zweignamen zu erwähnen (z.B. fix-1234).

Um einen fix-win11-build Funktionszweig zu erstellen, führen Sie aus:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Vermeiden Sie Scope Creep

"Scope creep" passiert, wenn die Liste der gelösten Probleme oder implementierten Funktionen durch einen einzelnen Beitrag deutlich über das hinausgeht, was zu Beginn der Arbeit beabsichtigt war. Sie fangen mit einem einfachen Problem an; Sie entdecken ein eng verwandtes Problem und beschließen, auch diese Lösung einzubeziehen; dann ein drittes… bevor Sie es merken, haben Sie einen Pull Request, der 5 Probleme schließt und 3 neue Funktionen hinzufügt, einschließlich Dutzende von Dateien.

Scope Creep passiert jedem. Ein Konzept, das erfahrenen Entwicklern nur allzu vertraut ist. Wir alle haben es schon mehrfach erlebt und alle damit verbundenen Probleme erfahren.

Es gibt sehr praktische Gründe, eine Ausweitung des Umfangs zu vermeiden. Je größer ein Beitrag wird, desto schwieriger ist es, mit ihm zu arbeiten. Es wird schwieriger, Randfälle oder potenzielle Probleme zu erkennen, was bedeutet, dass die Qualität des Beitrags insgesamt gemindert werden kann. Auch die Überprüfung wird schwieriger, wenn sich der Prüfer mit mehreren, möglicherweise nicht zusammenhängenden Kontexten befassen muss. Ein größerer Beitrag bedeutet mehr Überprüfungskommentare, und als Mitwirkender kann es schwierig werden, mehreren Überprüfungssträngen zu folgen. Sogar Ihre GitHub-Erfahrung wird darunter leiden - die Benutzeroberfläche von GitHub wird mit zunehmender Größe eines PR langsamer, was bedeutet, dass die Navigation durch die Dateien auf der GitHub-Benutzeroberfläche und der Versuch, Überprüfungskommentare zu hinterlassen, immer schwieriger wird.

Jedes Mal, wenn Sie einen Grund finden, etwas zu Ihrem Beitrag hinzuzufügen, das nicht explizit Teil des ursprünglichen Vorschlags oder Fehlerberichts ist, sollten Sie überlegen, ob Sie sich auf eine Ausweitung des Umfangs zubewegen. Gibt es zwei verschiedene Funktionen, die separat implementiert werden könnten? Könnte eine Funktion mit einer bekannten Einschränkung oder einem Fehler implementiert werden, und dieser Fehler in einem nachfolgenden Pull Request behoben werden? Ist ein Teil einer Fehlerbehebung unabhängig von einem anderen? Wenn ein Teil einer Änderung weggelassen werden kann, ohne den ursprünglichen Beitrag zu verändern, sollte es wahrscheinlich sein.

Die Entwicklung von Software ist immer ein Prozess der schrittweisen Verbesserung. Jeder einzelne Beitrag sollte die Codebasis in einem besseren Zustand hinterlassen, aber es ist völlig akzeptabel, Fehler oder Teile von Funktionen als Arbeit für zukünftige Verbesserungen zu hinterlassen. Das kann bedeuten, dass man eine Anfrage in mehrere Teile aufteilt, die unabhängig voneinander überprüft werden können, oder dass man einen Fehler protokolliert, damit jemand anderes das Problem untersuchen und beheben kann.

Die Begrenzung des Umfangs der einzelnen Beiträge hilft allen Beteiligten, auch Ihnen. Ihre Prüfer und auch Sie selbst werden es zu schätzen wissen.

Die neue Funktion implementieren

Um einen Fehler zu beheben oder eine Funktion zu implementieren, musst du neuen Code schreiben.

Wir haben einen Code-Styleguide, der unsere Richtlinien für das Schreiben von Code für BeeWare enthält.

Testgetriebene Entwicklung

Eine gute Methode, um sicherzustellen, dass Ihr Code das tut, was Sie erwarten, besteht darin, zunächst einen Testfall zu schreiben, um dies zu überprüfen. Dieser Testfall sollte zunächst fehlschlagen, da der zu testende Code noch nicht vorhanden ist. Anschließend können Sie die erforderlichen Codeänderungen vornehmen, damit der Test erfolgreich verläuft, und so sicher sein, dass das, was Sie geschrieben haben, das erwartete Problem löst.

Führen Sie Ihren Code aus

Sobald Ihr Code geschrieben ist, müssen Sie sicherstellen, dass er auch funktioniert. Sie müssen Ihren Code manuell ausführen, um zu überprüfen, ob er das tut, was Sie erwarten. Falls Sie dies noch nicht getan haben, sollten Sie einen Testfall für Ihre Änderungen erstellen; wie oben erwähnt, sollte dieser Test fehlschlagen, wenn Ihr Code auskommentiert ist oder fehlt.

Sie fügen Ihren Testfall zur Testsuite hinzu, damit er zusammen mit den anderen Tests ausgeführt werden kann. Als Nächstes führen Sie die Testsuite aus.

Tests und Abdeckung

BeeWare nutzt tox zur Verwaltung des Testprozesses und pytest für seine eigene Testsuite.

Der Standardbefehl tox umfasst die Ausführung von:

• Pre-Commit-Hooks
• towncrier Überprüfung der Versionshinweise

• Dokumentationsprüfung

• Testsuite für verfügbare Python-Versionen

• Berichte zur Codeabdeckung

Das ist im Wesentlichen das, was CI ausführt, wenn du einen Pull-Request einreichst.

Um die gesamte Testsuite auszuführen, geben Sie Folgendes ein:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Die Ausführung der vollständigen Testsuite kann eine Weile dauern. Sie können den Vorgang erheblich beschleunigen, indem Sie tox parallel ausführen, und zwar mit tox p (oder tox run-parallel). Wenn Sie die Testsuite parallel ausführen, erhalten Sie während der Ausführung weniger Rückmeldung zum Fortschritt, aber am Ende des Testlaufs erhalten Sie dennoch eine Zusammenfassung aller gefundenen Probleme. Sie sollten eine Ausgabe erhalten, die anzeigt, dass die Tests ausgeführt wurden. Möglicherweise sehen Sie SKIPPED Tests, sollten aber niemals FAIL oder ERROR Testergebnisse erhalten. Wir führen unsere vollständige Testsuite vor dem Zusammenführen jedes Patches aus. Wenn dabei Probleme entdeckt werden, führen wir den Patch nicht zusammen. Sollten Sie einen Testfehler oder einen Testausfall feststellen, liegt entweder ein Problem in Ihrer Testumgebung vor oder Sie haben einen Randfall entdeckt, den wir bisher noch nicht gesehen haben – in jedem Fall lassen Sie es uns wissen!

Neben dem Bestehen der Tests sollte hier eine 100 %ige Testabdeckung angezeigt werden.

Testvarianten ausführen

Tests für mehrere Python-Versionen ausführen

Standardmäßig versuchen viele der tox-Befehle, die Testsuite mehrmals auszuführen – einmal für jede von BeeWare unterstützte Python-Version. Dazu muss jedoch jede dieser Python-Versionen auf Ihrem Rechner installiert und für den Python-Erkennungsprozess von tox verfügbar sein. Im Allgemeinen gilt: Wenn eine Python-Version über (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery) verfügbar ist, sollte PATH in der Lage sein, sie zu finden und zu verwenden.

Führe nur die Testsuite aus

Wenn Sie an einer neuen Funktion zügig arbeiten, müssen Sie nicht die gesamte Testsuite ausführen; Sie können nur die Unit-Tests ausführen. Führen Sie dazu folgenden Befehl aus:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Eine Teilmenge von Tests ausführen

Standardmäßig führt tox alle Tests der Unit-Test-Suite aus. Wenn Sie einen neuen Test entwickeln, kann es hilfreich sein, nur diesen einen Test auszuführen. Dazu können Sie beliebige pytest Spezifikatoren als Argument an tox übergeben. Diese Testpfade beziehen sich relativ auf das briefcase Verzeichnis. Um beispielsweise nur die Tests in einer einzelnen Datei auszuführen, geben Sie Folgendes ein:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Auch wenn Sie nur einen Teil der Testsuite ausführen, erhalten Sie einen Abdeckungsbericht – allerdings werden in den Abdeckungsergebnissen nur die Codezeilen aufgeführt, die von den konkret ausgeführten Tests verarbeitet wurden.

Führe die Testsuite für eine bestimmte Python-Version aus

Standardmäßig wird tox -e py mit dem Interpreter ausgeführt, der auf Ihrem Rechner als python erkannt wird. Wenn Sie mehrere Python-Versionen installiert haben und eine bestimmte Python-Version aus den installierten Versionen testen möchten, können Sie eine bestimmte Python-Version angeben. Um beispielsweise die Testsuite unter Python 3.10 auszuführen, geben Sie Folgendes ein:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Eine Teilmenge von Tests kann ausgeführt werden, indem man -- und eine Testspezifikation an die Befehlszeile anhängt.

Die Testsuite ohne Abdeckung ausführen (schnell)

Standardmäßig führt tox die pytest-Suite im Single-Thread-Modus aus. Sie können die Ausführung der Testsuite beschleunigen, indem Sie sie parallel ausführen. In diesem Modus werden keine Abdeckungsdateien erstellt, da die Erfassung der Abdeckung innerhalb der gestarteten Prozesse zu komplex ist. Um eine einzelne Python-Version im „Fast“-Modus auszuführen, geben Sie Folgendes ein:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Eine Teilmenge von Tests kann ausgeführt werden, indem -- und eine Testspezifikation an die Befehlszeile angehängt werden; eine bestimmte Python-Version kann verwendet werden, indem die Version zum Testziel hinzugefügt wird (z. B. py310-fast für die Ausführung mit Python 3.10).

Codeabdeckung

BeeWare gewährleistet eine 100-prozentige Testabdeckung in seiner Codebasis. Wenn Sie Code zum Projekt hinzufügen oder ändern, müssen Sie Testcode hinzufügen, um sicherzustellen, dass alle vorgenommenen Änderungen abgedeckt sind.

Da BeeWare jedoch auf mehrere Plattformen sowie auf mehrere Python-Versionen abzielt, kann eine vollständige Abdeckung nicht auf einer einzigen Plattform und Python-Version überprüft werden. Um dem Rechnung zu tragen, sind im Abschnitt tool.coverage.coverage_conditional_plugin.rules von pyproject.toml mehrere bedingte Abdeckungsregeln definiert (z. B. kann no-cover-if-is-windows verwendet werden, um einen Code-Block zu kennzeichnen, der bei der Ausführung der Testsuite unter Windows nicht ausgeführt wird). Diese Regeln dienen dazu, Codeabschnitte zu identifizieren, die nur auf bestimmten Plattformen oder Python-Versionen abgedeckt sind.

Es ist zu beachten, dass die Berichterstellung zur Codeabdeckung bei verschiedenen Python-Versionen zu Unregelmäßigkeiten führen kann. Wenn beispielsweise die Codeabdeckungsdateien mit einer Python-Version erstellt wurden, die Berichterstellung jedoch mit einer anderen erfolgt, kann der Bericht falsche positive Ergebnisse für nicht abgedeckte Verzweigungen enthalten. Aus diesem Grund sollte für die Berichterstellung zur Codeabdeckung stets die älteste Python-Version verwendet werden, mit der die Codeabdeckungsdateien erstellt wurden.

Die Ergebnisse der Abdeckung verstehen

Am Ende der Ausgabe des Abdeckungstests sollte ein Bericht über die erfassten Abdeckungsdaten erscheinen:

Name    Stmts   Miss Branch BrPart   Deckung   Fehlende
 ---------------------------------------------------
 GESAMT    7540 0   1040 0  100,0 %

Das bedeutet, dass die Testsuite jeden möglichen Verzweigungsweg im Code durchlaufen hat. Das ist zwar keine hundertprozentige Garantie dafür, dass keine Fehler vorhanden sind, aber es bedeutet, dass wir jede einzelne Zeile des Codes in der Codebasis testen.

Wenn Sie Änderungen am Code vornehmen, kann es sein, dass dadurch eine Lücke in der Codeabdeckung entsteht. In diesem Fall zeigt Ihnen der Abdeckungsbericht an, welche Zeilen nicht ausgeführt werden. Nehmen wir zum Beispiel an, wir hätten eine Änderung an some/interesting_file.py vorgenommen und dabei neue Logik hinzugefügt. Der Abdeckungsbericht könnte dann etwa so aussehen:

Name Anweisungen   Fehlende Verzweigung BrPart  Abdeckung   Fehlende
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302–307, 320–335
 -------------------------------------------------------------------------------
 GESAMT 7540 1   1726 0  99,9 %

Dies bedeutet, dass Zeile 170, die Zeilen 302–307 sowie ein Sprung von Zeile 320 nach Zeile 335 von der Testsuite nicht ausgeführt werden. Sie müssen neue Tests hinzufügen (oder einen bestehenden Test anpassen), um diese Abdeckung wiederherzustellen.

Bericht zur Abdeckung für die Host-Plattform und die Python-Version

Sie können einen Abdeckungsbericht für Ihre Plattform und Python-Version erstellen. Um beispielsweise die Testsuite auszuführen und einen Abdeckungsbericht für Python 3.10 zu erstellen, geben Sie Folgendes ein:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Bericht zur Abdeckung der Host-Plattform

Wenn alle unterstützten Python-Versionen für tox verfügbar sind, kann die Abdeckung für die Host-Plattform durch Ausführen des folgenden Befehls ermittelt werden:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Berichterstattung in HTML

Ein HTML-Abdeckungsbericht kann erstellt werden, indem man an einen beliebigen Namen der Abdeckungsumgebung -html den Zusatz tox anhängt, zum Beispiel:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Es geht nicht nur darum, Tests zu schreiben!

Obwohl wir darauf achten, unseren gesamten Code zu testen, geht es bei dieser Aufgabe nicht nur darum, dieses Testniveau aufrechtzuerhalten. Ein Teil der Aufgabe besteht darin, den Code während der Entwicklung fortlaufend zu überprüfen. Man könnte zwar eine umfassende Reihe von Tests für eine bestimmte Rettungsweste schreiben … aber eine solche Rettungsweste wäre für den vorgesehenen Zweck dennoch unbrauchbar!

Bei der Entwicklung von Tests sollten Sie auch darauf achten, dass das Kernmodul intern konsistent ist. Wenn dir Methodennamen auffallen, die intern nicht konsistent sind (z. B. etwas, das in einem Modul on_select heißt, in einem anderen aber on_selected), oder wenn Daten nicht konsistent behandelt werden, markiere dies und mache uns darauf aufmerksam, indem du ein Ticket erstellst. Oder, wenn du dir sicher bist, was zu tun ist, erstelle einen Pull Request, der das von dir gefundene Problem behebt.

Dokumentation erstellen

Bevor Sie Änderungen an der Dokumentation von BeeWare vornehmen, sollten Sie sich vergewissern, dass Sie die vorhandene Dokumentation erstellen können.

Sie müssen einen Python 3.13 Interpreter installiert und in Ihrem Pfad verfügbar haben (d.h. python3.13 muss einen Python 3.13 Interpreter starten).

BeeWare verwendet tox zur Erstellung der Dokumentation. Die folgenden tox-Befehle müssen von demselben Ort aus ausgeführt werden wie die tox.ini-Datei, die sich im Stammverzeichnis des Projekts befindet.

Live-Vorschau der Dokumentation

Um die schnelle Bearbeitung der Dokumentation zu unterstützen, verfügt BeeWare über einen "Live-Vorschau"-Modus.

Die Live-Vorschau wird mit Warnungen erstellt!

Der Live-Serve steht Ihnen zur Verfügung, um Ihre Dokumentationsaktualisierungen zu wiederholen. Während Sie Dinge aktualisieren, können Sie ein Auszeichnungsproblem einführen. Probleme, die als WARNING eingestuft werden, führen dazu, dass ein Standard-Build fehlschlägt. Der Live-Serve ist jedoch so eingerichtet, dass er Warnungen in der Konsolenausgabe anzeigt, während der Build fortgesetzt wird. So können Sie iterieren, ohne die Live-Vorschau neu starten zu müssen.

Eine WARNING unterscheidet sich von einem ERROR. Wenn Sie ein Problem einführen, das als "ERROR" eingestuft wird, schlägt der Live-Service fehl und erfordert einen Neustart. Er wird erst dann wieder gestartet, wenn das WARNING-Problem behoben ist.

So starten Sie den Live-Server:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Dadurch wird die Dokumentation erstellt, ein Webserver gestartet, um die Dokumentation bereitzustellen, und das Dateisystem auf Änderungen an der Dokumentationsquelle überwacht.

Sobald der Server gestartet ist, sehen Sie in der Konsolenausgabe etwas wie das Folgende:

INFO    -  [11:18:51] Wird unter http://127.0.0.1:8000/ bereitgestellt

Öffnen Sie einen Browser, und navigieren Sie zu der angegebenen URL. Nun können Sie mit der Bearbeitung der Dokumentation beginnen. Wenn eine Änderung festgestellt wird, wird die Dokumentation neu erstellt, und jeder Browser, der die geänderte Seite anzeigt, wird automatisch aktualisiert.

docs-live" ist ein erster Schritt

Das Ausführen von docs-live, um mit dem Live-Server zu arbeiten, ist für erste Iterationen gedacht. Sie sollten immer einen lokalen Build ausführen, bevor Sie einen Pull-Request einreichen.

Lokales Gebäude

Sobald Sie mit der Iteration fertig sind, müssen Sie einen lokalen Build der Dokumentation durchführen. Dieser Build-Prozess ist so konzipiert, dass er bei Auszeichnungsproblemen fehlschlägt. So können Sie alles auffangen, was Sie auf dem Live-Server übersehen haben könnten.

Erzeugen eines lokalen Builds

Um ein lokales Build zu erstellen:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Die Ausgabe dieses Builds befindet sich im Verzeichnis _build im Stammverzeichnis des Projekts.

Erzeugen eines lokal übersetzten Builds

Die Dokumentation von BeeWare ist in mehrere Sprachen übersetzt. Aktualisierungen der englischen Dokumentation können zu Problemen in den anderen Sprach-Builds führen. Es ist wichtig, dass Sie überprüfen, ob alle Builds funktionieren, bevor Sie einen Pull Request einreichen.

Um ein Build aller verfügbaren Übersetzungen zu erstellen:

macOSLinuxWindows

(Verb) $ tox -e docs-all

(Verb) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Die Ausgabe jedes Sprach-Builds befindet sich im zugehörigen Verzeichnis _build/html/<languagecode>, wobei <languagecode> der zwei- oder fünfstellige Sprachcode ist, der der jeweiligen Sprache zugeordnet ist (z.B. fr für Französisch, it für Italienisch, usw.).

Wenn Sie ein Problem mit einem einzelnen Build finden, können Sie diesen einzelnen Build separat ausführen, indem Sie tox -e docs-<Sprachcode> ausführen. Um zum Beispiel nur die französische Dokumentation zu erstellen, führen Sie aus:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Die Ausgabe eines einsprachigen Builds befindet sich im Verzeichnis _build.

Linting der Dokumentation

Der Erstellungsprozess erkennt Markdown-Probleme, aber BeeWare führt einige zusätzliche Prüfungen für Stil und Formatierung durch, die als "Linting" bekannt sind. So führen Sie die Lint-Prüfungen durch:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Dadurch wird sichergestellt, dass die Dokumentation keine Angaben enthält:

• tote Hyperlinks
• falsch geschriebene Wörter

Wenn eine gültige Schreibweise eines Wortes als falsch erkannt wird, dann fügen Sie das Wort der Liste in docs/spelling_wordlist hinzu. Dadurch wird das Wort in das Wörterbuch der Rechtschreibprüfung aufgenommen. Denken Sie beim Hinzufügen zu dieser Liste daran:

• Wir bevorzugen die US-amerikanische Rechtschreibung, mit einigen Freiheiten für programmierspezifische Umgangssprache (z. B. "Apps") und Verben von Substantiven (z. B. "scrollable")
• Jeder Verweis auf einen Produktnamen sollte die bevorzugte Großschreibung des Produkts verwenden. (z. B. "macOS", "GTK", "pytest", "Pygame", "PyScript").
• Wenn ein Begriff "als Code" verwendet wird, sollte er als Literal zitiert werden (wie dies) und nicht in das Wörterbuch aufgenommen werden.

Dokumentation schreiben

Dies sind die Schritte, die Sie befolgen müssen, um Ihren Dokumentationsbeitrag zu BeeWare zu schreiben.

Aktualisierung der bestehenden Dokumentation

Wenn Sie die vorhandenen Dokumente bearbeiten, müssen Sie die Datei im Verzeichnis /docs/de suchen. Die Dateistruktur folgt der Seitenstruktur, so dass Sie die Datei über die URL der Dokumentation finden können.

Hinzufügen einer neuen Dokumentation

Wenn Sie ein neues Dokument hinzufügen, sind ein paar weitere Schritte erforderlich.

Sie müssen das Dokument an der entsprechenden Stelle im Verzeichnis docs/de erstellen. Für die Diskussion nehmen wir an, Sie fügen ein neues Dokument mit dem Dateinamen "new_doc.md" hinzu.

Dann müssen Sie die Datei docs/de/SUMMARY.md aktualisieren, um Ihre neue Datei aufzunehmen. Die Datei SUMMARY.md ist so organisiert, dass sie im Wesentlichen die Verzeichnisstruktur von docs/de widerspiegelt, aber, was noch wichtiger ist, sie bestimmt direkt die Struktur der linken Seitenleiste. Wenn Sie den Abschnitt finden, in den Sie new_doc.md einbinden wollen, brauchen Sie nichts in SUMMARY.md zu ändern, wenn Sie einen Platzhalterpfad aufgeführt sehen. Zum Beispiel:

- ./Pfad/zum/Verzeichnis/*

Wenn der Abschnitt, in den Sie new_doc.md einfügen wollen, eine Liste von einzelnen Markdown-Links ist, müssen Sie einen expliziten Link zu Ihrem eigenen hinzufügen. Zum Beispiel:

- [Mein neues Dokument](new_doc.md)

Verfassen Ihrer Dokumentation

Sie können nun die gewünschte Datei in Ihrem Editor öffnen und mit dem Schreiben beginnen.

Wir haben einen Dokumentationsleitfaden, der unsere Richtlinien für die Erstellung der Dokumentation für BeeWare umreißt.

Änderungsnotiz 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.

Einen Pull-Request einreichen

Jetzt, wo Sie alle Ihre Änderungen übertragen haben, können Sie einen Pull-Request einreichen. Um einen reibungslosen Überprüfungsprozess zu gewährleisten, sollten Sie eine Reihe von Schritten unternehmen.

Arbeiten mit Pre-Commit

Wenn Sie eine Änderung übertragen, wird automatisch ein Pre-Commit durchgeführt. Wenn bei der Übergabe Probleme gefunden werden, schlägt die Übergabe fehl. Wenn möglich, nimmt pre-commit die notwendigen Änderungen vor, um die gefundenen Probleme zu beheben. Im folgenden Beispiel wurde durch die "ruff"-Prüfung ein Fehler in der Codeformatierung gefunden:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

In diesem Fall hat ruff das Problem automatisch behoben, so dass Sie alle Dateien, die als Ergebnis der Pre-Commit-Prüfungen geändert wurden, wieder hinzufügen und die Änderung erneut committen können. Bei einigen Prüfungen müssen Sie jedoch manuelle Änderungen vornehmen. Sobald Sie diese Änderungen vorgenommen haben, fügen Sie alle geänderten Dateien wieder hinzu und übertragen die Änderung erneut.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Wenn alles erfolgreich war, sehen Sie eine Meldung, dass der Commit abgeschlossen wurde, und Ihr Git-Protokoll zeigt Ihren Commit als die neueste Ergänzung an. Sie sind nun bereit, die Datei auf GitHub zu veröffentlichen.

Pushen Sie Ihre Änderungen auf GitHub und erstellen Sie Ihre Pull-Anfrage

Wenn Sie das erste Mal auf GitHub pushen, erhalten Sie eine URL, die Sie direkt zur GitHub-Seite führt, um eine neue Pull-Anfrage zu erstellen. Folgen Sie der URL und erstellen Sie Ihre Pull-Anfrage.

Das folgende Beispiel zeigt, was bei push zu erwarten ist, wobei die URL hervorgehoben ist.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Wenn Sie den aktuellen Zweig bereits auf GitHub gepusht haben, werden Sie die URL nicht mehr erhalten. Es gibt jedoch andere Möglichkeiten, die URL für die PR-Erstellung zu erhalten:

• Navigieren Sie zum Upstream-Repository, klicken Sie auf "Pull Requests" und anschließend auf "New pull request" und wählen Sie das Repository aus, von dem aus Sie Ihren Pull Request einreichen möchten.
• Wenn Sie kürzlich gepusht haben, navigieren Sie zum Upstream-Repository, suchen Sie das Banner über der Liste der Dateien, das anzeigt, dass das Projektarchiv "kürzlich gepusht" wurde, und klicken Sie auf die Schaltfläche "Vergleichen & Pull-Anfrage".
• Verwenden Sie den GitHub-CLI-Befehl "gh pr create", und füllen Sie die Eingabeaufforderungen aus.
• Verwenden Sie den GitHub CLI-Befehl "gh pr create –web", um einen Webbrowser zu öffnen, der die PR-Erstellungsseite anzeigt.

Mit jeder dieser Optionen können Sie Ihre neue Pull-Anfrage erstellen.

Die GitHub-CLI: gh

GitHub stellt die GitHub CLI zur Verfügung, mit der Sie von Ihrem Terminal aus über den Befehl "gh" auf viele Funktionen von GitHub zugreifen können. Die GitHub CLI-Dokumentation behandelt alle Funktionen.

Inhalt der Pull-Anfrage

Der Titel einer Pull-Anfrage muss informativ, klar und prägnant sein. Versuchen Sie, ihn möglichst kurz zu halten, aber längere Titel sind akzeptabel, wenn nötig. Ein guter PR-Titel sollte einer Person ohne jeglichen Kontext eine einigermaßen solide Vorstellung davon geben, welcher Fehler oder welche Funktion durch Ihren PR implementiert wird.

Die PR-Beschreibung muss die Änderungen in der PR klar widerspiegeln. Eine Person ohne jeglichen Kontext sollte in der Lage sein, Ihre Beschreibung zu lesen und relativ vollständig zu verstehen, warum die Änderung vorgenommen wird. Vermeiden Sie Witze, Redewendungen, umgangssprachliche Ausdrücke und unnötige Formatierungen, wie z. B. Großbuchstaben oder übermäßige Interpunktion; dies soll eine direkte Erklärung dessen sein, was in Ihrer PR geschieht, und die Vermeidung dieser Dinge macht die Beschreibung für andere leichter verständlich.

Wenn es Reproduktionsfälle oder Testverfahren gibt, die Sie verwendet haben und die nicht bereits Teil der Änderungen in der PR sind, sollten diese erläutert und in die PR aufgenommen werden. Die Erklärung sollte beinhalten, wie man sie durchführt und was man tun muss, um das gewünschte Ergebnis zu reproduzieren.

Wenn Ihr Pull Request den Fehler #1234 behebt, sollten Sie den Text `Fixes

1234` in Ihre Pull Request Beschreibung einfügen. Dies wird dazu führen, dass

das Problem automatisch geschlossen wird, wenn der Pull Request zusammengeführt wird. Sie können auf andere Diskussionen, Issues oder Pull Requests verweisen, indem Sie die gleiche Syntax #1234 verwenden. Sie können auf eine Ausgabe in einem anderen Repository verweisen, indem Sie der Nummer ein Präfix voranstellen - zum Beispiel würde python/cpython#1234 auf die Ausgabe 1234 im CPython Repository verweisen.

Kontinuierliche Integration

Kontinuierliche Integration, oder CI, ist der Prozess, bei dem automatisierte Prüfungen für Ihre Pull-Anfrage durchgeführt werden. Dazu können einfache Prüfungen gehören, wie z. B. die Sicherstellung, dass der Code richtig formatiert ist, aber auch die Durchführung der Testsuite und die Erstellung der Dokumentation.

Es gibt eine Vielzahl von Änderungen, die zu CI-Fehlern führen können. Generell gilt, dass wir einen PR, der die KI nicht durchläuft, nicht prüfen werden. Wenn Sie eine Pull-Anforderung erstellen und die KI fehlschlägt, beginnen wir erst mit der Überprüfung, wenn sie erfolgreich ist. Wenn Ihre Änderungen zu einem Fehler führen, liegt es in Ihrer Verantwortung, den Grund zu untersuchen und das Problem zu beheben.

Wenn die CI fehlschlägt, werden die Fehlerlinks unten auf der PR-Seite unter der Überschrift "Einige Prüfungen waren nicht erfolgreich" angezeigt. Sie sehen eine Liste der fehlgeschlagenen Prüfungen, die am Anfang der Liste aller Prüfungen angezeigt wird, wenn es auch erfolgreiche Prüfungen gibt. Wenn Sie auf den Link "Fehler" klicken, gelangen Sie zum Protokoll. Das Protokoll enthält oft alle Informationen, die Sie benötigen, um herauszufinden, was den Fehler verursacht hat. Lesen Sie das Protokoll durch und versuchen Sie herauszufinden, warum der Fehler auftritt, und tun Sie dann das Nötige, um ihn zu beheben.

Gelegentlich schlägt ein CI-Check aus Gründen fehl, die nichts mit Ihren Änderungen zu tun haben. Das kann an einem Problem auf dem Rechner liegen, der die CI-Prüfung durchführt, oder daran, dass eine CI-Prüfung instabil ist. Wenn Sie einen Fehler feststellen und sich ziemlich sicher sind, dass er nichts mit Ihren Änderungen zu tun hat, fügen Sie Ihrem PR einen entsprechenden Kommentar hinzu, und wir werden uns die Sache ansehen.

Um einen neuen CI-Lauf auszulösen, müssen Sie neue Änderungen in Ihren Zweig übertragen.

Wenn Sie sich in einer Situation befinden, in der Sie Hilfe benötigen, um eine Informatisierung zu erreichen, hinterlassen Sie einen Kommentar auf der PR-Website, und wir werden tun, was wir können, um zu helfen.

Die "Pre-Commit"- und "Citycrier"-Kontrollen

Wenn entweder die pre-commit- oder die towncrier-Prüfung fehlschlägt, werden die meisten anderen CI-Prüfungen nicht ausgeführt. Sie müssen die entsprechenden Probleme beheben, bevor der gesamte Satz von Prüfungen ausgeführt werden kann.

Wir haben nur begrenzte KI-Ressourcen. Es ist wichtig zu verstehen, dass jedes Mal, wenn Sie in den Zweig pushen, CI gestartet wird. Wenn Sie eine Reihe von Änderungen vornehmen wollen, ist es besser, diese Änderungen lokal vorzunehmen und sie alle auf einmal zu pushen. CI wird nur die letzte Übergabe in einem Batch ausführen, um die Belastung unseres CI-Systems zu minimieren.

Der Prozess der Einreichung Ihres PR ist erst dann abgeschlossen, wenn er von der Kommission genehmigt wurde oder Sie eine Erklärung dafür abgeben können, warum er nicht genehmigt wurde.