Überblick

Alle Änderungen am Code und der Dokumentation sollten (/contributing/first-time/github/) über eine Pull-Anfrage an das GitHub-Repository für das Projekt eingereicht werden.

Für die meisten Projekte gibt es einen speziellen Leitfaden für Beiträge mit Einzelheiten für dieses Projekt oder für bestimmte Arten von Beiträgen. Diese Dokumentation kann auf Read the Docs gefunden werden. Zum Beispiel, [Briefcase's Dokumentation] (https://briefcase.readthedocs.io) enthält Anleitungen Anleitungen sowohl für Code und Dokumentation.

Alle Beiträge müssen dem BeeWare Code of Verhaltenskodex entsprechen.

Anmerkungen ändern

Mehrere BeeWare-Projekte, vor allem Briefcase und Toga, verlangen, dass jede Pull-Anfrage mit einer Änderungsnotiz eingereicht wird. Diese Änderungsnotizen werden zusammengeführt, wenn eine neue Version für das Projekt erstellt wird. die Versionshinweise für die neue Version.

BeeWare verwendet Towncrier zur Änderungsnotizen zu verwalten.

Eine Änderungsnotizdatei sollte im Verzeichnis changes erstellt werden und mit diesem Format benannt werden:

<PR/Issue #>.<Change Type>.rst

Eine Pull-Anfrage, die das GitHub-Problem #42 behebt, würde zum Beispiel folgendermaßen heißen 42.bugfix.rst". Wenn eine Pull-Anfrage nicht mit einem bestimmten Problem verbunden ist Problem verbunden ist, kann stattdessen die Pull-Request-Nummer verwendet werden. Sie müssen eventuell Pull Request ohne eine Änderungsnotiz erstellen, um eine Pull Request Nummer zugewiesen zu bekommen und dann ein Update zu veröffentlichen, das die Änderungsnotiz mit der mit der neu vergebenen Pull Request Nummer.

Die Änderungsarten für die Änderungsnotiz sollten eine der folgenden sein:

  • Feature
  • Bugfix
  • Doku
  • Entfernen
  • Sonstiges

Der Typ misc ist für Änderungen reserviert, die keine Auswirkungen auf die Benutzer haben und die nicht in den Versionshinweisen vermerkt werden müssen. Kleinere typographische Korrekturen in der Dokumentation, Aktualisierungen der CI-Konfiguration und Fehlerbehebungen für Funktionen, die noch nicht formell veröffentlicht wurden, sind Beispiele für Funktionen, die mit der Markierung misc beschrieben werden.

Eine Änderungsnotiz sollte aus einer einzigen Textzeile bestehen, die eine Zusammenfassung der Änderung aus der Sicht des Benutzers, keine detaillierte 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. Eine Änderungsnotiz ist eine "benutzerseitige" Beschreibung, die sich auf die neue Fähigkeit bezieht die als Ergebnis der Änderung verfügbar ist. Es kann hilfreich sein, sich die Änderungsnotiz als eine Pressemitteilung zu betrachten, die die Änderung ankündigt, anstatt eine Commit-Beschreibung.

Wenn Sie zum Beispiel einen Fehler beheben, der durch die Datumsverarbeitung verursacht wurde, könnte die Commit Nachricht oder die Pull Request Beschreibung lauten können:

Ein MM-DD-YYYY-Format-Validator wurde zur DateWidget-Validierungskette Kette.

Hier wird die Änderung beschrieben, die an der Implementierung vorgenommen wurde - ein Detail die für die Person, die den Code überprüft, hilfreich sein werden. Allerdings könnte die entsprechende Änderungsnotiz könnte etwa so lauten:

Datums-Widgets können nun Datumsangaben im US-Format akzeptieren.

Dies beschreibt die funktionale Änderung, wie sie von den Endbenutzern erlebt wird. Benutzer. Ein Benutzer kann diese Beschreibung lesen, ohne etwas über die über die Implementierung wissen.

Code style

Die Projekte von BeeWare verwenden Pre-commit, um die Einhaltung des Codestils zu automatisieren. Diese Prüfungen werden in der Datei Datei .pre-commit-config.yaml für jedes Repository definiert und werden automatisch in CI ausgeführt, wenn ein Pull Request geöffnet wird.

Um die Pre-commit-Prüfungen in Ihrer lokalen Entwicklungsumgebung zu automatisieren zu automatisieren, führen Sie pre-commit install bei jeder Übergabe von git aus.

Eingeschlossene Pre-Commit-Prüfungen:

  • Schwarz gewährleistet einheitliche Code-Formatierung
  • docformatter sorgt für einheitliche Formatierung für docstrings und Kommentare
  • pyupgrade stellt sicher, dass der Code die neuesten Best Practices für Python verwendet
  • isort sorgt für einheitliche import Anweisungen
  • flake8 prüft auf allgemeine Kodierungs und Syntaxprobleme
  • Verschiedene Prüfungen, die strukturierte Dokumente wie TOML-Dateien validieren und unnötige Leerzeichen entfernen

Zusätzliche Leitlinien:

  • Vermeiden Sie die Verwendung von "wir" in Kommentaren, z. B. "Loop over" statt "We loop over über"

  • Verwenden Sie Unterstriche, nicht camelCase, für Variablen-, Funktions- und Methodennamen Namen

  • Verwenden Sie InitialCaps für Klassennamen (oder für Fabrikfunktionen, die Klassen)

  • Verwenden Sie Dokumentationsstrings im Sphinx-Stil und 257; Typ-Anmerkungen mit 484 sind optional, aber empfohlen.

    Zum Beispiel:

    def function_name(param1: int, param2: str) -> bool:
    """Beispielfunktion mit Typen und einem Docstring.

    :param param1: Der erste Parameter.
    :param param2: Der zweite Parameter.

    :gibt zurück: Der Rückgabewert. True für Erfolg, sonst False.
    """

  • Geben Sie in den Testdokumentationen das erwartete Verhalten an, das jeder Test demonstriert. Verzichten Sie auf Präambeln wie "Testet, dass" oder "Stellt sicher dass".

  • Reservieren Sie Ticketreferenzen für obskure Probleme, bei denen das Ticket zusätzliche Details enthält, die sich nicht ohne Weiteres in Docstrings oder Kommentare. Fügen Sie die Ticketnummer am Ende eines Satzes ein wie so:

    def test_foo():
    """Ein Test-Docstring sieht so aus (#123456)."""

  • Sofern nicht anders angegeben, folgen Sie 8 (unter sorgfältiger Beachtung von Abschnitt 2).