Zum Inhalt

Dokumentation hinzufügen

Sie können die beste Software der Welt haben - aber was nützt das, wenn niemand weiß, wie man sie benutzt? Die Dokumentation kann immer verbessert werden - und wir brauchen Ihre Hilfe!

Dokumentationsformulare

Die Dokumentation von BeeWare wird mit MkDocs und Markdown geschrieben. Wir streben an, den Diataxis Rahmen für die Strukturierung der Dokumentation zu befolgen.

Der Diataxis-Rahmen beschreibt vier "Formen" der Dokumentation:

  • Tutorial - Eine geführte Lernerfahrung mit einem bestimmten Projektziel.
  • Anleitung - Anweisungen, die den Leser zu einem bestimmten Ziel oder Ergebnis führen.
  • Themenleitfaden - Eine Erörterung eines einzelnen Gedankens, die so erklärt wird, dass die zugrunde liegenden Konzepte klar sind.
  • Referenz - Technische Beschreibungen von spezifischen APIs oder anderen Schnittstellen.

Bevor Sie mit einem Beitrag zur Dokumentation beginnen, sollten Sie herausfinden, welche Form am besten geeignet ist. Viele Dokumentationsvorschläge werden zunächst als Anfrage nach einem "Tutorial zu X" beschrieben - in den meisten Fällen handelt es sich jedoch um eine Anleitung, einen Themenleitfaden oder verbesserte Referenzinformationen.

Nehmen wir als Beispiel die Aufgabe, eine Dokumentation über das Backen von Keksen zu schreiben.

Tutorial

Ein Tutorial ist eine Einführung, die sich vor allem an Anfänger richtet und deren Ziel es sein sollte, den Leser von einem sauberen Ausgangspunkt zu einem fertigen Produkt zu bringen. Es erfordert sehr spezifische Anweisungen und detaillierte Erklärungen, die die Schritte des Tutorials in einen Kontext stellen. Sie dürfen nichts über die Erfahrung des Lesers mit dem zu erklärenden Werkzeug voraussetzen, obwohl es vernünftig ist, einige grundlegende Python-Kenntnisse vorauszusetzen.

Das Lernprogramm sollte regelmäßige Kontrollpunkte enthalten, an denen der Leser feststellen kann, ob er das Beschriebene erfolgreich durchgeführt hat. An jedem Kontrollpunkt sollten die Erfolgskriterien klar sein. Bekannte Fehlersituationen sollten klar umrissen werden, einschließlich Erklärungen zu möglichen Fehlern oder Problemen, auf die der Leser stoßen könnte. Dinge, die sich aufgrund der vom Leser durchgeführten Maßnahmen ändern, sollten hervorgehoben werden, auch wenn sie offensichtlich erscheinen. Wiederholungen sind erwünscht, vor allem, wenn Sie versuchen, eine bewährte Praxis oder gemeinsame Prozesse zu etablieren. Erklärungen von Interna sollten vermieden werden, ebenso wie alternative Wege zum gleichen Ergebnis.

Eine Anleitung zum Plätzchenbacken ist mehr als nur ein Rezept. Die Anleitungen in einer Anleitung sollten auch für jemanden verständlich sein, der noch nie gebacken hat (z. B. ein Kind), und sie müssen Dinge berücksichtigen, die für einen erfahrenen Bäcker selbstverständlich sind, z. B. wie man Zucker und Butter cremig rührt, wie man den Ofen vorheizt oder wie lange die Kekse vor dem Verzehr abkühlen müssen. Das Ziel des Tutorials ist nicht die Herstellung eines Kekses, sondern die Vermittlung der Grundlagen des Backens. Der fertige Keks ist der Leckerbissen, der jemanden davon überzeugt, das Tutorial überhaupt zu machen.

Leitfaden

Ein Leitfaden sollte sich auf einen konkreten Anwendungsfall und praktische Ergebnisse konzentrieren, nicht auf theoretische Erklärungen. Im Gegensatz zu einem Tutorium können Sie eine gewisse Vertrautheit mit bestehenden Tools voraussetzen. Der Leser sollte in der Lage sein, dem Leitfaden von Anfang bis Ende zu folgen und das Ziel zu erreichen, aber er benötigt dazu möglicherweise einige Vorkenntnisse. Er sollte eine Reihe konkreter Anweisungen oder logischer Schritte enthalten, die befolgt werden müssen, um das Ziel des Leitfadens zu erreichen.

Ein Rezept in einem Kochbuch ist ein gutes Beispiel für eine Gebrauchsanweisung. Es gibt viele Rezepte für Schokoladenkekse, und sie alle haben Gemeinsamkeiten, aber ein bestimmtes Rezept sollte von Anfang bis Ende nachvollziehbar sein und zu einem einheitlichen Ergebnis führen. Ein gutes Rezept für Schokoladenkekse wird sich nicht mit den Vorzügen verschiedener Zucker- oder Mehlsorten befassen oder detaillierte Anweisungen zu grundlegenden Techniken oder Verfahren geben; es wird lediglich die Zutaten und Anweisungen zum Backen einer Charge Kekse enthalten, wobei vorausgesetzt wird, dass der Leser mit dem Backen grundsätzlich vertraut ist.

Themenführer

Ein Themenleitfaden beschreibt ein einzelnes Thema oder eine Idee. Er kann Beispielcode oder Anleitungen enthalten, ist aber eher darauf ausgerichtet, ein Gesamtkonzept auf hohem Niveau zu vermitteln. Er kann auch Meinungen und alternative Sichtweisen enthalten, aber der Fokus auf das spezifische Thema des Leitfadens sollte beibehalten werden.

Ein thematischer Leitfaden über das Backen von Keksen könnte sich mit der Geschichte des Kekses als Backprodukt befassen, die Art und Weise erforschen, wie industriell hergestellte Kekse im Vergleich zu selbst gebackenen Keksen zu unterschiedlichen Arten von Keksen führen, oder Wege aufzeigen, wie Kekse in eine ausgewogene Ernährung integriert werden können. Für sich genommen wäre es kein sehr nützliches Dokument, wenn Sie einen Keks backen wollten, aber es könnte den Hintergrund liefern, der es jemandem, der mit dem Backen vertraut ist, ermöglichen würde, ein bestehendes Keksrezept erfolgreich anzupassen.

Referenz

Referenzdokumentation ist informationsorientiert und beschreibt die Besonderheiten der Funktionsweise einer Werkzeugbibliothek. Sie kann oft aus dem Code selbst generiert werden, aber eine gute API-Dokumentation kann weitere Erklärungen und Kontext erfordern. Auch wenn sie manchmal Beispiele für die Verwendung enthält, sollten detaillierte Erklärungen vermieden werden.

Ein Referenzhandbuch für das Backen könnte die möglichen Zuckersorten beschreiben und ihre Eigenschaften beim Backen aufzeigen. Er würde wörtliche Fakten über Zucker beschreiben, aber eine umfassendere Diskussion über die Wahl zwischen verschiedenen Zuckersorten sollte Gegenstand einer Anleitung oder eines Themenleitfadens sein. Die Nährwertangaben, die auf den meisten verpackten Lebensmitteln zu finden sind, würden als Referenzdokumente gelten.

Stil der Dokumentation

Die Dokumentation von BeeWare folgt den Richtlinien, die im documentation style guide beschrieben sind. Dieser Leitfaden enthält grundlegende Stil- und Formatierungsregeln sowie den Prozess der Rechtschreibprüfung. Außerdem werden verschiedene Details der Markdown-Syntax behandelt, wie z. B. die Syntax für Referenzlinks, Tipps für die Arbeit mit Codeblöcken und die Behandlung von Bildern.

Dokumentation beisteuern

Vorschlag für neue Dokumentation

Sie haben also eine Idee für eine Verbesserung für BeeWare - Wie können Sie diese Idee zur Prüfung einreichen?

Recherchieren Sie

Der erste Schritt besteht darin, den BeeWare issue tracker nach bestehenden feature issues (issues tagged "enhancement"), [documentation issues (issues tagged "documentation")] (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Adocumentation&type=issues), oder Discussion threads um zu sehen, ob die Idee schon einmal vorgeschlagen wurde. Wenn dies der Fall ist und Sie neue Zusammenhänge oder Ideen hinzufügen möchten, fügen Sie diese in das bestehende Thema ein. Wenn Sie Hilfe bei Ihrer Recherche benötigen, können Sie im #dev-Kanal im BeeWare Discord nachfragen. Wir können Ihnen vielleicht Hinweise auf bestehende Threads geben, Ihnen einen Kontext liefern, der Ihnen nicht bekannt ist, oder Ihre Idee mit einer anderen Idee in Verbindung bringen, die auf den ersten Blick nicht verwandt ist.

Diskutieren Sie die Idee

Wenn Sie keine Hinweise auf Ihre Idee finden, starten Sie einen Diskussionsfaden. Beschreiben Sie in groben Zügen den Zweck und den Anwendungsfall für Ihre Idee. Machen Sie sich Gedanken darüber, wie die Funktion aussehen würde, wenn sie implementiert würde, z.B. die allgemeine Form einer API, das visuelle Erscheinungsbild einer Fähigkeit oder das Dokument, das hinzugefügt würde. Falls zutreffend, sollten Sie auch Untersuchungen darüber anstellen, wie Ihre Idee auf verschiedenen Plattformen aussehen würde.

Sobald der Diskussionsstrang eröffnet ist, werden das BeeWare-Team und der Rest der Community darauf reagieren. Das Kernteam wird sich bemühen, innerhalb von zwei Werktagen zumindest einen ersten Eindruck von Ihrer Idee zu vermitteln. Wenn eine Idee besonders komplex ist, kann eine detailliertere Analyse bis zu einer Woche dauern. Aufgrund von Ereignissen wie Feiertagen und Konferenzen kann sich diese Zeitspanne etwas verlängern.

Dies ist Ihre Gelegenheit, an einem Gespräch über Ihre Idee teilzunehmen. Wir können Sie um weitere Details oder Zusammenhänge bitten. Andere Mitglieder der Gemeinschaft können sich ebenfalls an der Diskussion beteiligen und andere Perspektiven, Vorschläge oder Gegenvorschläge einbringen. Das Ergebnis dieser Diskussion wird über die nächsten Schritte entscheiden.

Es ist wichtig zu verstehen, dass nicht alle Ideen akzeptiert werden. Der Grund, warum dieser Prozess mit einem Vorschlag beginnt, ist, dass Sie nicht die ganze Arbeit investieren müssen, nur um dann herauszufinden, dass es einen Grund gibt, warum Ihre Änderung nicht angenommen wird.

Das heißt aber nicht, dass es keine gute Idee war! Es kann technische Gründe dafür geben, dass sie nicht umgesetzt werden kann. Zum Beispiel könnten wir eine Idee ablehnen, wenn:

  • Es wäre schwierig oder unmöglich, sie auf allen unterstützten Plattformen zuverlässig zu implementieren; oder
  • Es wäre schwierig zu warten, oder die Wartung würde den Zugang zu einer Technologie oder Software erfordern, die nicht allgemein verfügbar ist; oder
  • Sie dient einem Nischenpublikum, bedeutet aber für andere Nutzer einen erheblichen Mehraufwand.

Wenn wir feststellen, dass Ihre Idee nicht passt, bedeutet das nicht unbedingt, dass Sie sie aufgeben sollten. Auch wenn wir eine bestimmte Idee ablehnen, können wir viel eher bereit sein, eine Plugin-Schnittstelle oder einen anderen Erweiterungspunkt hinzuzufügen, der es Ihnen ermöglicht, die gleiche Funktion als externe Bibliothek zu pflegen. Auf diese Weise können Sie die Funktion haben, ohne dass die spezifischen Wartungsprobleme oder Einschränkungen der Funktion zu einer Einschränkung für das Projekt selbst werden.

Umwandlung in einen formellen Antrag auf eine neue Funktion

Sobald die Diskussion einen Konsens über die Form eines Features erreicht hat, können Sie einen neuen [Feature Request issue] (https://github.com/beeware/beeware/issues/new/choose) im BeeWare issue tracker erstellen, der die Diskussion zusammenfasst und für den Kontext auf die Diskussion verweist.

Sie müssen Ihren Vorschlag für eine neue Funktion nicht selbst umsetzen; Sie können ein Problem mit den Details Ihres Vorschlags eröffnen. Allerdings bedeutet das bloße Veröffentlichen des Themas nicht, dass es für Sie implementiert werden wird. Sie müssen abwarten, bis es möglicherweise von jemand anderem aufgegriffen wird, der an der gleichen Funktion interessiert ist, sei es ein anderes Community-Mitglied oder das Kernteam; dies ist jedoch nicht garantiert. Wenn Sie die garantierte Implementierung wünschen, müssen Sie sie selbst implementieren oder jemanden bezahlen, der sie für Sie implementiert.

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.

Gebäudedokumentation

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:

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