Zum Inhalt

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.

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:

$ python3 --version

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:

$ python3 --version

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:

Forken Sie das BeeWare Repository, und dann:

$ git clone https://github.com/<your username>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Forken Sie das BeeWare Repository, und dann:

$ git clone https://github.com/<your username>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Forken Sie das BeeWare Repository, und dann:

C:\...>git clone https://github.com/<your username>/beeware.git

(ersetzen Sie Ihren GitHub-Benutzernamen)

Erstellen einer virtuellen Umgebung

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

$ 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:

(.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:

(.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:

(.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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

  • pre-commit hooks
  • towncrier release note check

  • documentation linting

  • test suite for available Python versions

  • code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations

Run tests for multiple versions of Python

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

(.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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
INSGESAMT 7540 0 1040 0 100,0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Name Stmts Miss Branch BrPart Cover Missing
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98.1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
INSGESAMT 7540 1 1726 0 99,9

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

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

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

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

Coverage reporting in HTML

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

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

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

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

It's not just about writing tests!

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | 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.

/// warning | 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:



/// tab | macOS



```console
(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] Serving on http://127.0.0.1:8000/

Ö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:

(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:

(venv) $ tox -e docs-all

(venv) $ 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:

(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:

(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:

- ./path/to/directory/*

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:

- [My new document](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:

(.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.

(.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.

(.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.