Pull-Request-Richtlinien #

Pull Requests (PRs) sind der Mechanismus, um zum Code und zur Dokumentation von Matplotlibs beizutragen.

Zusammenfassung für Pull-Request-Autoren #

Notiz

  • Wir schätzen Beiträge von Menschen mit allen Erfahrungsstufen. Gerade wenn es Ihre erste PR ist, muss nicht alles perfekt sein. Wir führen Sie durch den PR-Prozess.

  • Versuchen Sie dennoch, die folgenden Richtlinien so gut wie möglich zu befolgen, um den PR-Prozess schnell und reibungslos zu gestalten.

  • Seien Sie geduldig mit Rezensenten. Wir versuchen unser Bestes, um schnell zu reagieren, aber wir haben eine begrenzte Bandbreite. Wenn Sie innerhalb von ein paar Tagen kein Feedback erhalten, senden Sie uns bitte einen Ping, indem Sie einen Kommentar zu Ihrer PR posten.

Achten Sie bei einer PR auf Folgendes:

  • Zielen Sie auf den Hauptzweig .

  • Beachten Sie die Coding-Richtlinien .

  • Aktualisieren Sie gegebenenfalls die Dokumentation .

  • Ziel ist es, die PR so "ready-to-go" wie möglich zu machen. Dies hilft, den Überprüfungsprozess zu beschleunigen.

  • Es ist in Ordnung, unvollständige oder in Arbeit befindliche PRs zu öffnen, wenn Sie Hilfe oder Feedback von den Entwicklern benötigen. Sie können diese auf GitHub als Entwürfe für Pull-Requests markieren.

  • Wenn Sie Ihre PR aktualisieren, ziehen Sie bitte in Betracht, anstatt neue Commits hinzuzufügen, um etwas zu beheben, Ihre ursprünglichen Commits zu ändern, um den Verlauf sauber zu halten. Dies erreichen Sie mit

    git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease

Siehe auch Beitragen , um zu erfahren, wie man eine PR erstellt.

Zusammenfassung für Prüfer von Pull-Anforderungen #

Notiz

  • Wenn Sie Commit-Rechte haben, wird Ihnen vertraut, diese zu verwenden. Bitte helfen Sie mit, PRs zu überprüfen und zusammenzuführen!

  • Seien Sie geduldig und freundlich mit Mitwirkenden.

Inhaltliche Themen:

  • Ist das Feature / Bugfix sinnvoll?

  • Entspricht der PR den Coding-Richtlinien ?

  • Ist die Dokumentation (Docstrings, Beispiele, was ist neu, API-Änderungen) aktualisiert?

Organisatorische Themen:

Detaillierte Richtlinien #

Dokumentation #

  • Jede neue Funktion sollte dokumentiert werden. Wenn es sich um ein neues Modul handelt, vergessen Sie nicht, eine neue rst-Datei zu den API-Dokumenten hinzuzufügen.

  • Jede High-Level-Plotting-Funktion sollte ein kleines Beispiel im ExamplesAbschnitt des Docstring enthalten. Dies sollte so einfach wie möglich sein, um die Methode zu demonstrieren. Komplexere Beispiele sollten in eine dedizierte Beispieldatei im examplesVerzeichnis aufgenommen werden, die in der Beispielgalerie in der Dokumentation gerendert wird.

  • Erstellen Sie die Dokumente und stellen Sie sicher, dass alle Formatierungswarnungen behandelt werden.

  • Siehe Verfassen von Dokumentation für unseren Dokumentations-Styleguide.

  • Wenn es sich bei Ihrer Änderung um eine wichtige neue Funktion handelt, fügen Sie einen Eintrag zu hinzu doc/users/whats_new.rst.

  • Wenn Sie die API auf abwärtsinkompatible Weise ändern, dokumentieren Sie dies bitte, indem Sie eine Datei im entsprechenden Unterverzeichnis von hinzufügen doc/api/next_api_changes/, wahrscheinlich im behavior/ Unterverzeichnis.

Etiketten #

  • Wenn Sie die Rechte zum Festlegen von Labels haben, kennzeichnen Sie die PR mit aussagekräftigen Labels. Siehe Liste der Labels .

  • Wenn der PR Änderungen an der Laufradbauaktion vornimmt, fügen Sie das Label "Run cibuildwheel" hinzu, um das Testen von Laufrädern zu ermöglichen.

Meilensteine ​​#

  • Setzen Sie den Meilenstein nach diesen Regeln:

    • Neue Funktionen und API-Änderungen sind Meilensteine ​​für die nächste Nebenversion v3.X.0.

    • Bugfixes und Docstring-Änderungen sind Meilensteine ​​für die nächste Patch-Versionv3.X.Y

    • Dokumentationsänderungen (alle .rst-Dateien und Beispiele) sind Meilensteine v3.X-doc

    Wenn mehrere Regeln zutreffen, wählen Sie die erste Übereinstimmung aus der obigen Liste aus.

    Das Setzen eines Meilensteins impliziert oder garantiert nicht, dass ein PR für diese Version zusammengeführt wird, aber wenn er zusammengeführt würde, in welcher Version er sich befinden würde.

    Alle diese PRs sollten auf den Hauptzweig abzielen. Das Meilenstein-Tag löst einen automatischen Backport für Meilensteine ​​aus, die einen entsprechenden Zweig haben.

Zusammenführen #

  • Dokumentation und Beispiele können vom Erstgutachter zusammengeführt werden. Verwenden Sie die Schwelle "Ist das besser als es war?" als Überprüfungskriterien.

  • Bei Codeänderungen (alles in srcoder lib) sollten mindestens zwei Kernentwickler (diejenigen mit Commit-Rechten) alle Pull-Requests überprüfen. Wenn Sie der Erste sind, der eine PR überprüft und die Änderungen genehmigt, verwenden Sie das GitHub -Tool „Approve Review“ , um sie als solche zu markieren. Wenn Sie ein nachfolgender Überprüfer sind, genehmigen Sie bitte die Überprüfung, und wenn Sie der Meinung sind, dass keine weitere Überprüfung erforderlich ist, führen Sie die PR zusammen.

    Stellen Sie sicher, dass alle API-Änderungen in einer Datei in einem der Unterverzeichnisse von dokumentiert sind doc/api/next_api_changesund wichtige neue Funktionen einen Eintrag in haben doc/user/whats_new.

    • Wenn ein PR bereits eine positive Bewertung hat, kann sich ein Kernentwickler (z. B. der erste Bewerter, aber nicht notwendigerweise) für die Zusammenführung dieses PR einsetzen. Dazu sollten sie alle Core-Entwickler sowohl auf GitHub als auch auf der Entwickler-Mailingliste anpingen und die PR mit dem Hinweis „Merge with single review?“ kennzeichnen. Etikett. Andere Core-Entwickler können dann entweder die PR überprüfen und zusammenführen oder ablehnen oder einfach eine zweite Überprüfung beantragen, bevor sie zusammengeführt werden. Wenn innerhalb einer Woche niemand nach einer solchen zweiten Bewertung fragt, kann der PR auf der Grundlage dieser einzigen Bewertung zusammengeführt werden.

      Ein Core-Entwickler sollte immer nur für eine PR werben, und wir sollten versuchen, den Strom der geförderten PRs angemessen zu halten.

  • Führen Sie keine Selbstzusammenführung aus, außer bei „kleinen“ Patches, um das CI wieder in Ordnung zu bringen, oder wenn ein anderer Prüfer dies ausdrücklich erlaubt (z.

Automatisierte Tests #

Immer wenn eine Pull-Anforderung erstellt oder aktualisiert wird, werden verschiedene automatisierte Testtools auf allen unterstützten Plattformen und Versionen von Python ausgeführt.

  • Stellen Sie vor dem Zusammenführen sicher, dass die Linting-, GitHub Actions-, AppVeyor-, CircleCI- und Azure-Pipelines erfolgreich sind (alle Prüfungen sind unten auf der GitHub-Seite Ihrer Pull-Anfrage aufgeführt). Hier sind einige Tipps, um die Ursache des Testfehlers zu finden:

    • Wenn Linting fehlschlägt, liegt ein Problem mit dem Codestil vor, das als Anmerkungen im Diff der Pull-Anfrage aufgeführt wird.

    • Wenn eine Ausführung von GitHub Actions oder AppVeyor fehlschlägt, durchsuchen Sie das Protokoll nach FAILURES. Der folgende Abschnitt enthält Informationen zu den nicht bestandenen Tests.

    • Wenn CircleCI fehlschlägt, haben Sie wahrscheinlich ein Problem mit dem reStructuredText-Stil in den Dokumenten. Suchen Sie im CircleCI-Protokoll nach WARNING.

    • Wenn Azure-Pipelines mit einem Bildvergleichsfehler fehlschlagen, finden Sie die Bilder als Artefakte des Azure-Jobs:

      • Klicken Sie bei der Überprüfung auf der GitHub-PR-Seite auf Details .

      • Klicken Sie auf Weitere Details zu Azure Pipelines anzeigen , um zu Azure zu wechseln.

      • Auf der Übersichtsseite werden Artefakte im Abschnitt Related aufgelistet .

  • Codecov und LGTM dienen derzeit nur der Information. Ihr Versagen ist nicht unbedingt ein Blocker.

  • tox wird bei den automatisierten Tests nicht verwendet. Es wird zum Testen vor Ort unterstützt.

  • Wenn Sie wissen, dass Ihre Änderungen nicht getestet werden müssen (das kommt sehr selten vor!), können alle CIs für ein bestimmtes Commit übersprungen werden, indem Sie oder in die Commit-Nachricht aufnehmen. Wenn Sie wissen, dass nur eine Teilmenge von CIs ausgeführt werden muss (z. B. wenn Sie einen Block mit einfachem reStructuredText ändern und nur CircleCI ausführen möchten, um das Ergebnis zu rendern), können einzelne CIs auch bei einzelnen Commits übersprungen werden, indem Sie Folgendes verwenden Teilstrings in Commit-Nachrichten:[ci skip][skip ci]

    • GitHub-Aktionen:[skip actions]

    • AppVeyor: (muss in der ersten Zeile des Commit stehen)[skip appveyor]

    • Azure-Pipelines:[skip azp]

    • CircleCI:[skip circle]

Anzahl Commits und Squashing #

  • Squashing ist von Fall zu Fall. Das Gleichgewicht besteht zwischen der Belastung des Beitragenden, dem Führen einer relativ sauberen Historie und dem Führen einer Historie, die für die Halbierung verwendbar ist. Die einzige Zeit, in der wir wirklich streng damit umgehen, ist die Eliminierung von Binärdateien (z. B. mehrfache Neugenerierungen von Testbildern) und die Entfernung von Upstream-Merges.

  • Lassen Sie das Perfekte nicht der Feind des Guten sein, insbesondere nicht für Dokumentationen oder Beispiel-PRs. Wenn Sie feststellen, dass Sie viele kleine Vorschläge machen, öffnen Sie entweder einen PR gegen den ursprünglichen Zweig, übertragen Sie Änderungen an den Contributor-Zweig oder führen Sie den PR zusammen und öffnen Sie dann einen neuen PR gegen den Upstream.

  • Wenn Sie zu einem Contributor-Zweig pushen, hinterlassen Sie einen Kommentar, in dem Sie erklären, was Sie getan haben, z. Wenn Sie wesentliche Änderungen am Code oder der Absicht der PR vornehmen möchten, wenden Sie sich bitte zuerst an den Mitwirkenden.

Branches und Backports #

Aktuelle Filialen #

Die derzeit aktiven Branches sind

hauptsächlich

Die aktuelle Entwicklungsversion. Zukünftige Nebenversionen ( v3.N.0 ) werden davon abgezweigt.

v3.Nx

Wartungszweig für Matplotlib 3.N. Zukünftige Patch-Releases werden davon abzweigen.

v3.NM-doc

Dokumentation für die aktuelle Version. Bei einer Patch-Version wird dies durch einen richtig benannten Zweig für die neue Version ersetzt.

Branch-Auswahl für Pull-Requests #

Im Allgemeinen sollten alle Pull-Anforderungen auf den Hauptzweig abzielen.

Andere Filialen werden automatisch oder manuell beschickt . Nur in seltenen Fällen ist es für spezielle Wartungsarbeiten notwendig, direkt auf andere Zweige zu zielen.

Backport-Strategie #

Wir werden immer zum Patch-Release-Zweig ( v3.Nx ) zurückportieren:

  • kritische Fehlerbehebungen (Segfault, Importfehler, Dinge, die der Benutzer nicht umgehen kann)

  • Korrekturen für Regressionen gegenüber den letzten beiden Versionen.

Alles andere (Regressionen gegen ältere Versionen, Bugs/API-Inkonsistenzen, die der Benutzer in seinem Code umgehen kann) ist von Fall zu Fall abhängig, sollte risikoarm sein und braucht jemanden, der sich für den Backport einsetzt und ihn durchführt.

Die einzigen Änderungen, die in den Dokumentationszweig ( v3.NM-doc ) zurückportiert werden müssen, sind Änderungen an doc, examples, oder tutorials. Jegliche Änderungen an liboder srceinschließlich reiner Docstring-Änderungen sollten nicht in diesen Zweig zurückportiert werden.

Automatisierte Backports #

Wir verwenden den meeseeksdev-Bot, um Zusammenführungen automatisch auf die richtige Wartungszweigbasis auf dem Meilenstein zurückzuportieren. Um richtig zu funktionieren, muss der Meilenstein vor dem Zusammenführen gesetzt werden. Wenn Sie Commit-Rechte haben, kann der Bot nach einem Merge auch manuell ausgelöst werden, indem Sie eine Nachricht auf dem PR hinterlassen. Wenn es Konflikte gibt, werden Sie von meeseekdevs darüber informiert, dass die Rückportierung manuell durchgeführt werden muss.@meeseeksdev backport to BRANCH

Der Zielzweig wird konfiguriert, indem die Meilensteinbeschreibung in eine eigene Zeile eingefügt wird.on-merge: backport to TARGETBRANCH

Wenn der Bot nicht wie erwartet funktioniert, melden Sie Probleme bitte Meeseeksdev .

Manuelle Backports #

Wenn Sie Backports durchführen, kopieren Sie bitte das von meeseekdev verwendete Formular, . Wenn Sie Konflikte manuell lösen müssen, notieren Sie sie und wie Sie sie in der Commit-Nachricht gelöst haben.Backport PR #XXXX: TITLE OF PR

Wir machen einen Backport von main auf v2.2.x unter der Annahme:

  • matplotlibist ein schreibgeschützter Remote-Zweig des matplotlib/matplotlib-Repos

Das TARGET_SHAist der Hash des Merge-Commits, den Sie zurückportieren möchten. Dies kann auf der GitHub-PR-Seite (in der Benutzeroberfläche mit der Merge-Benachrichtigung) oder über die Git-CLI-Tools abgelesen werden.

Angenommen, Sie haben bereits einen lokalen Zweig v2.2.x(wenn nicht, dann ) und dass Ihr Remote- Zweig aufgerufen wird :git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

Dateien mit Konflikten können mit aufgelistet werden und müssen manuell behoben werden (Suche auf ). Sobald der Konflikt gelöst ist, müssen Sie die Datei(en) erneut zum Zweig hinzufügen und dann mit der Rosinenauswahl fortfahren:git status>>>>>

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

Verwenden Sie Ihr Ermessen, um direkt zum Upstream zu pushen oder einen PR zu öffnen; Stellen Sie sicher, dass Sie Push oder PR gegen den v2.2.xUpstream-Zweig durchführen, nicht main!