Community Guide

Ein Leitfaden zur Beteiligung an SQLAlchemy und den zugehörigen Projekten.

Auch wenn diese Abschnitte möglicherweise für Entwickler des Kernprojekts SQLAlchemy geschrieben wurden, gelten die verschiedenen Richtlinien, insbesondere der Verhaltenskodex, für alle Projekte, die im Repository der SQLAlchemy-Organisation gehostet werden.

Entwickeln

Dieser Abschnitt beschreibt, wo Sie Informationen zur Entwicklung finden und gibt einige Tipps für den Einstieg.

Entwickler-Community

Wo finden Sie die Entwickler von SQLAlchemy?

Die Entwickler von SQLAlchemy bitten alle, die an diesen Kanälen teilnehmen, den Verhaltenskodex zu respektieren, wenn sie Unterstützung suchen oder geben.

  • Github-Diskussionen
    • Das Forum Github Discussions ist am gebräuchlichsten – Kernentwickler unterstützen Benutzer bei Problemen aller Art. Alle SQLAlchemy-Benutzer und Autoren von Drittanbieter-Bibliotheken werden ermutigt, hier Unterstützung zu suchen.
  • Echtzeitkommunikation
    • Diskussionen zur Entwicklung finden die ganze Woche über im Gitter-Raum sqlalchemy/devel statt. Diskussionen in diesem Raum sind für Benutzer gedacht, die daran interessiert sind, Code, Tests, Dokumentationen oder andere Entwicklungsressourcen beizutragen. Dieser Kanal ist derzeit das bevorzugte Medium für Echtzeitdiskussionen für SQLAlchemy-Mitwirkende und beherbergt die geplanten Entwicklertreffen. Gitter-basierte Unterstützung ist über den Gitter-Raum sqlalchemy/community verfügbar; weitere Informationen hierzu finden Sie auf der Seite Support.

Geplante Entwicklertreffen

Regelmäßig findet ein virtuelles Echtzeit-Meeting von Kernentwicklern und Mitwirkenden im Gitter-Raum sqlalchemy/devel statt. Dieses Treffen ist wöchentlich zu einer festen Zeit geplant, dies kann jedoch je nach Verfügbarkeit der erforderlichen Mitglieder variieren. Vor jedem Treffen enthält der Raum einen Link zu einem Dokument mit Datum, Uhrzeit und Agenda für das nächste geplante Treffen; derzeit erscheint dies in der "Betreffzeile" oder im "Titel" des Raumes. Diese Treffen und ihre Protokolle sind öffentlich zugänglich. Benutzer, die daran interessiert sind, Code, Tests, Dokumentationen oder andere Entwicklungsressourcen beizutragen, werden ermutigt, teilzunehmen.

Zugriff auf den Quellcode

Der Quellcode von SQLAlchemy wird mit Git versioniert. Das primäre öffentliche Repository befindet sich auf GitHub

Pull Requests

Pull Requests werden im GitHub-Repository unter https://github.com/sqlalchemy/sqlalchemy eingereicht. Sobald ein Pull Request zur Überprüfung angenommen wurde und, vorausgesetzt, er ändert den Code selbst und nicht nur Korrekturen an der Dokumentation, erfolgt die Code-Überprüfung in unserem Gerrit-System unter https://gerrit.sqlalchemy.org, wo wir ihn mit einem hohen Maß an Kontrolle und kollaborativer Fähigkeit überprüfen, modifizieren und durch kontinuierliche Integrationstests laufen lassen können. Der Pull Request wird mit einem Link zur Überprüfung in Gerrit geschlossen. Pull Requests für Codeänderungen werden niemals direkt zusammengeführt.

Bitte beachten Sie die Richtlinien für Pull Requests, die den Quellcode ändern (z. B. nicht nur die Dokumentation)

  • Es ist bevorzugt, ein Issue im Issue-Tracker einzureichen, bevor ein Pull Request eingereicht wird, insbesondere bei größeren Änderungen. Es kommt häufig vor, dass Pull Requests entweder nicht beschreiben, welches Problem sie lösen sollen, oder das Problem auf unangemessene oder suboptimale Weise lösen. Wenn ein Bug- oder Feature-Issue im Voraus eröffnet wird, können wir den Anwendungsfall verstehen und den besten Ansatz diskutieren, bevor der Mitwirkende den Aufwand betreibt, den Code und die Tests zu schreiben.
  • Fügen Sie immer Tests zu Code-Änderungen hinzu – SQLAlchemy committet keine Code-Änderungen ohne entsprechenden Test – jede Zeile Code, die nicht getestet wird, ist technisch gesehen selbst ein Fehler. Wenn ein Pull Request ohne Tests eingereicht wird, kann er nicht gemergt werden, bis ein Test geschrieben ist. Es ist äußerst häufig, dass wir einen einzeiligen Pull Request erhalten, für den wir jedoch viele Dutzende von Zeilen schreiben müssen, um ihn zu testen, da 99 % der Arbeit für jede Codeänderung im Schreiben der Tests besteht. Bitte reichen Sie keine einzeiligen PRs ohne Tests ein. Reichen Sie nur einen vollständigen Fehlerbericht für Codeänderungen ein, für die Sie keine Tests bereitstellen können.
  • Bitte folgen Sie bei Änderungsanfragen zu Pull Requests nach und abonnieren Sie die Gerrit-Überprüfung, um Kommentare zu erhalten. – Pull Requests, auf die bei angeforderten Änderungen nicht reagiert wird, werden geschlossen.
  • Bitte stellen Sie sicher, dass Ihre Entwicklungsumgebung so konfiguriert ist, dass sie die aktuellen Anforderungen an die Entwicklungsumgebung erfüllt. Dies hilft sicherzustellen, dass Ihre PRs automatische Tests bestehen.

Tests

Eine wichtige Aufgabe für jeden, der auch nur kleine Features oder Fehler beheben möchte, ist es, mit dem Ausführen der Tests vertraut zu sein und im Idealfall Tests schreiben zu können. SQLAlchemy hat über viele Tausende von Tests, die sich von Unit- bis zu Integrationstests erstrecken, und ein vollständiger CI-Lauf über mehrere Python-Versionen und Datenbank-Backends umfasst weit über zweihunderttausend einzelne Tests. Der mit Abstand größte Teil der Entwicklungsarbeit, sowohl am bestehenden Codebestand als auch bei der Implementierung neuer Features oder Fehlerbehebungen, besteht im Schreiben vollständiger Tests. Die Tests für eine bestimmte Änderung oder ein Feature umfassen im Allgemeinen fünf- bis zehnmal so viele Codezeilen wie der Code für das eigentliche Verhalten. Sie können auch viel schwieriger zu schreiben sein als das eigentliche Feature, da sie oft eine breite Palette von schwer vorhersehbaren Varianten des Zielverhaltens, die Injektion von Verhalten zu Testzwecken, die Abfangen von generiertem SQL, Events oder Elementen der DBAPI-Nachrichten erfordern.

Tests werden mit py.test ausgeführt. Eine umfassende Anleitung zum Ausführen der Tests finden Sie in der Datei README.unittests, die im Quellcode-Paket enthalten ist. Diese Datei erklärt detailliert, wie Tests in verschiedenen Bereichen ausgeführt werden können, einschließlich des Ausführens für bestimmte Datenbanken und der Auswahl bestimmter Tests.

Die Tests selbst wurden über viele Jahre hinweg geschrieben und haben sich stilistisch weiterentwickelt. Wir versuchen, alte Tests an neuere Stile anzupassen, während wir in unseren Methoden kompetenter und fortgeschrittener werden, aber es gibt immer noch viele Tests, die einer Aktualisierung bedürfen. Unser aktueller bevorzugter Stil, unter Berücksichtigung der Tatsache, dass viele unserer Tests sicherlich noch nicht in diesem Stil sind, ist wie folgt:

  • Tests sollten PEP8 einhalten. Viele ältere Tests tun dies derzeit nicht; dies ist ein Bereich, in dem wir neue Hilfe willkommen heißen.
  • Testen Sie nur eine Sache. Eine Reihe von einzelnen Assertionen werden am besten in einzelne Testmethoden aufgeteilt, anstatt eine Testmethode mit mehreren Assertionen.
  • Halten Sie den Zustand pro Test als lokal zu einer Test-Fixture. Das heißt, wenn eine Reihe von Tests alle gegen eine bestimmte Tabellenstruktur durchgeführt werden, sollte die Test-Fixture die Tabellenmetadaten vorbereiten und sie mit self oder cls verknüpfen. Die Test-Suite verfügt über Standard-Fixtures, die diesen Prozess erheblich erleichtern, unter test/lib/fixtures.py.
  • Testen Sie nicht gegen ein Datenbank-Backend, wenn es nicht notwendig ist. Viele Arten von Tests müssen nur sicherstellen, dass ein bestimmter SQL-String gerendert wird. Wir haben eine umfassende Sammlung von Fixtures, die es ermöglichen, SQL-Strings zu erfassen und zu überprüfen, ohne dass eine Datenbank-Round-Trip erforderlich ist.

Kontinuierliche Integration

Das SQLAlchemy-Projekt verwendet Jenkins für kontinuierliche Integration. Unsere Read-Only-Jenkins-Schnittstelle ist unter https://jenkins.sqlalchemy.org verfügbar.

Dokumentation

Die Dokumentation wird mit Sphinx erstellt. Neue Entwickler können sehr hilfreich sein, wenn sie bereit sind, neue Dokumentationen zu schreiben oder an bestehenden Dokumentationen zu arbeiten, neue Beispiele hinzuzufügen, Tippfehler zu beheben, die Verlinkung zwischen Dokumentationen zu verbessern. Dies ist auch eine der wichtigsten und schwierigsten Arbeiten für das Projekt. Wie beim Testen nimmt gute Dokumentation eine deutlich größere Zeit in Anspruch als das Feature selbst, das dokumentiert wird. Es macht den meisten Entwicklern nicht so viel Spaß, Dokumentationen zu schreiben wie tatsächlichen Code, aber ein Entwickler, der dazu bereit und in der Lage ist, ist für das Projekt äußerst wertvoll.

Code-Richtlinien

Wir hoffen, diesen Abschnitt zu erweitern. Vorerst einige wichtige Dinge, die Sie beachten sollten:

  • Versuchen Sie, sich so weit wie möglich an PEP8 zu halten. Unsere Zeilenbreite beträgt 78 Zeichen und wir neigen dazu, Zeilen mit Backslashes statt Klammern zu brechen; insbesondere SQLAlchemy-generative Abfragen sind am besten entlang von Backslashes aufgeteilt zu lesen.
  • Neue Features können nur hinzugefügt werden, wenn sie eine zugehörige Dokumentation haben, die unter Sphinx läuft.
  • Kein Feature oder keine Fehlerbehebung wird jemals ohne vollständige Unit-Tests soweit wie möglich committet.
  • Bitte stellen Sie sicher, dass Ihre Entwicklungsumgebung so konfiguriert ist, dass sie die aktuellen Anforderungen an die Entwicklungsumgebung erfüllt. Dies hilft sicherzustellen, dass Ihre PRs automatische Tests bestehen.

Entwicklungsumgebung

Das SQLAlchemy-Projekt hat kürzlich einige Konventionen während der Entwicklung standardisiert, von denen die meisten automatisch von einer ordnungsgemäß konfigurierten Entwicklungsumgebung erzwungen werden können.

  • Die Formatierung des Quellcodes und andere Hilfsprogramme werden automatisch mithilfe von Hooks im pre-commit-Framework angewendet. `pre-commit` kann durch Ausführen von pip install pre-commit installiert werden.
  • Der Quellcode wird mit dem black der Python Software Foundation formatiert. `black` kann durch Ausführen von pip install black installiert werden, jedoch sollte `pre-commit` es in den meisten Fällen automatisch installieren.

Zusammenfassend lässt sich sagen: Stellen Sie sicher, dass pre-commit in Ihrer Umgebung installiert ist, bevor Sie mit der Arbeit an einem Pull Request beginnen.