Zum Inhalt

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

Ihr Pull-Request erfordert möglicherweise zusätzliche Inhalte, wie z. B. eine Änderungsnotiz, bevor er überprüft werden kann.