Wege zur Mitarbeit#

Dieses Dokument soll einen Überblick über die Möglichkeiten geben, wie man zu SciPy beitragen kann. Es versucht, häufig gestellte Fragen zu beantworten und Einblicke in die praktische Funktionsweise des Community-Prozesses zu geben. Leser, die mit der SciPy-Community vertraut sind und erfahrene Python-Programmierer sind, möchten vielleicht direkt zum SciPy-Leitfaden für Mitwirkende springen.

Es gibt viele Möglichkeiten, wie Sie beitragen können

  • Neuen Code beisteuern

  • Fehler beheben, Dokumentation verbessern und andere Wartungsarbeiten durchführen

  • Offene Pull-Requests prüfen

  • Issues triagieren

  • An der scipy.org Website arbeiten

  • Fragen beantworten und am Forum teilnehmen.

Neuen Code beisteuern#

Wenn Sie schon eine Weile mit dem wissenschaftlichen Python-Toolstack arbeiten, haben Sie wahrscheinlich Code herumliegen, bei dem Sie denken: "Das könnte auch für andere nützlich sein". Vielleicht ist es dann eine gute Idee, ihn zu SciPy oder einem anderen Open-Source-Projekt beizusteuern. Die erste Frage, die Sie sich stellen sollten, ist: Wohin gehört dieser Code? Diese Frage ist hier schwer zu beantworten, also beginnen wir mit einer spezifischeren: Welcher Code eignet sich für SciPy? Fast aller neuer Code, der zu SciPy hinzugefügt wird, hat gemeinsam, dass er potenziell in mehreren wissenschaftlichen Domänen nützlich ist und in den Umfang bestehender SciPy-Unterpakete passt (siehe Entscheidungen über neue Funktionen). Grundsätzlich können auch neue Unterpakete hinzugefügt werden, dies ist jedoch weitaus seltener. Für Code, der spezifisch für eine einzelne Anwendung ist, gibt es möglicherweise ein bestehendes Projekt, das den Code nutzen kann. Einige SciKits (scikit-learn, scikit-image, statsmodels usw.) sind hierfür gute Beispiele; sie haben einen engeren Fokus und dadurch mehr domänenspezifischen Code als SciPy.

Wenn Sie nun Code haben, den Sie gerne in SciPy aufnehmen würden, wie gehen Sie vor? Nachdem Sie geprüft haben, ob Ihr Code unter einer kompatiblen Lizenz in SciPy vertrieben werden kann (siehe Lizenzüberlegungen), ist der erste Schritt, dies im scipy-dev Forum zu besprechen. Alle neuen Funktionen sowie Änderungen an bestehendem Code werden dort diskutiert und entschieden. Sie können, und sollten wahrscheinlich, diese Diskussion bereits beginnen, bevor Ihr Code fertig ist. Denken Sie daran, dass Ihr Code von jemand anderem geprüft werden muss, um in SciPy aufgenommen zu werden. Versuchen Sie also, jemanden zu finden, der bereit ist, Ihre Arbeit zu prüfen, während Sie dabei sind.

Unter der Annahme, dass das Ergebnis der Diskussion im Forum positiv ist und Sie eine Funktion oder einen Codeabschnitt haben, der das tut, was Sie brauchen, wie geht es dann weiter? Bevor Code in SciPy aufgenommen wird, muss er zumindest eine gute Dokumentation, Unit-Tests, Benchmarks und einen korrekten Code-Stil aufweisen.

  1. Unit-Tests

    Grundsätzlich sollten Sie darauf abzielen, Unit-Tests zu erstellen, die den gesamten von Ihnen hinzugefügten Code abdecken. Dies gibt einen gewissen Grad an Sicherheit, dass Ihr Code korrekt läuft, auch auf Python-Versionen und Hardware oder Betriebssystemen, die Ihnen nicht zur Verfügung stehen. Eine ausführliche Beschreibung, wie man Unit-Tests schreibt, finden Sie in den Testrichtlinien, und SciPy-Tests lokal ausführen beschreibt, wie Sie diese ausführen.

  2. Benchmarks

    Unit-Tests prüfen die Funktionalität; Benchmarks messen die Code-Performance. Nicht aller bestehende SciPy-Code hat Benchmarks, aber er sollte es haben: Da SciPy wächst, wird es zunehmend wichtiger, die Ausführungszeiten zu überwachen, um unerwartete Regressionen zu erkennen. Weitere Informationen zum Schreiben und Ausführen von Benchmarks finden Sie in Benchmarking von SciPy mit airspeed velocity.

  3. Dokumentation

    Eine klare und vollständige Dokumentation ist unerlässlich, damit Benutzer den Code finden und verstehen können. Dokumentation für einzelne Funktionen und Klassen – die mindestens eine grundlegende Beschreibung, Typ und Bedeutung aller Parameter und Rückgabewerte sowie Anwendungsbeispiele im doctest-Format enthält – wird in Docstrings platziert. Diese Docstrings können innerhalb des Interpreters gelesen und in einem Referenzhandbuch im HTML- und PDF-Format kompiliert werden. Eine höherstufige Dokumentation für Schlüsselbereiche (oder Bereiche) der Funktionalität wird in Tutorial-Form und/oder in Modul-Docstrings bereitgestellt. Eine Anleitung zum Schreiben von Dokumentation finden Sie in den Dokumentationsstil, und Dokumentation lokal mit Sphinx rendern erklärt, wie Sie die Dokumentation in der Vorschau anzeigen können, wie sie online erscheinen wird.

  4. Code-Stil

    Ein einheitlicher Code-Stil erleichtert anderen das Lesen Ihres Codes. SciPy folgt der Standard-Python-Stilrichtlinie PEP8, mit der Ausnahme, dass die empfohlene maximale Zeilenlänge 88 Zeichen beträgt und nicht 79 Zeichen wie in PEP8.

    Wir stellen einen Git-Pre-Commit-Hook bereit, der jeden Ihrer Commits auf korrekten Stil prüft. Installieren Sie ihn (einmalig), indem Sie vom Stammverzeichnis des SciPy-Repository aus Folgendes ausführen

    cp tools/pre-commit-hook.py .git/hooks/pre-commit

    Alternativ können Sie den Linter manuell ausführen

    python dev.py lint

    Die meisten IDEs und Texteditoren verfügen auch über Einstellungen, die Ihnen helfen, PEP8 zu befolgen, z. B. durch die Übersetzung von Tabs in vier Leerzeichen. Weitere Informationen finden Sie unter PEP8 und SciPy.

Eine Checkliste, die diese und andere Anforderungen enthält, finden Sie am Ende des Beispiels Entwicklungs-Workflow.

Eine weitere Frage, die Sie vielleicht haben: Wo genau platziere ich meinen Code? Um diese Frage zu beantworten, ist es hilfreich zu verstehen, wie die öffentliche API (Application Programming Interface) von SciPy definiert ist. Bei den meisten Modulen ist die API zwei Ebenen tief, was bedeutet, dass Ihre neue Funktion als scipy.subpackage.my_new_func erscheinen sollte. my_new_func kann in einer bestehenden oder neuen Datei unter /scipy/<subpackage>/ platziert werden, ihr Name wird der __all__-Liste in dieser Datei hinzugefügt (die alle öffentlichen Funktionen in der Datei auflistet), und diese öffentlichen Funktionen werden dann in /scipy/<subpackage>/__init__.py importiert. Alle privaten Funktionen/Klassen sollten einen führenden Unterstrich (_) in ihrem Namen haben. Eine detailliertere Beschreibung der öffentlichen API von SciPy finden Sie unter SciPy API.

Sobald Sie der Meinung sind, dass Ihr Code für die Aufnahme in SciPy bereit ist, können Sie einen Pull Request (PR) auf Github senden. Wir gehen hier nicht ins Detail, wie man mit Git arbeitet, das ist gut beschrieben in Git für die Entwicklung und auf den Github-Hilfeseiten. Wenn Sie den PR für eine neue Funktion senden, erwähnen Sie dies unbedingt auch im scipy-dev Forum. Dies kann interessierte Personen dazu anregen, bei der Überprüfung Ihres PRs zu helfen. Unter der Annahme, dass Sie bereits zuvor positives Feedback zur allgemeinen Idee Ihres Codes/Ihrer Funktion erhalten haben, besteht der Zweck der Code-Überprüfung darin, sicherzustellen, dass der Code korrekt, effizient ist und die oben genannten Anforderungen erfüllt. In vielen Fällen geschieht die Code-Überprüfung relativ schnell, aber es ist möglich, dass sie ins Stocken gerät. Wenn Sie bereits gegebenes Feedback vollständig umgesetzt haben, ist es völlig in Ordnung, im Forum erneut um eine Überprüfung zu bitten (nachdem eine angemessene Zeit, z. B. ein paar Wochen, vergangen ist). Sobald die Überprüfung abgeschlossen ist, wird der PR in den "main"-Branch von SciPy zusammengeführt.

Das Obige beschreibt die Anforderungen und den Prozess für das Hinzufügen von Code zu SciPy. Es beantwortet jedoch noch nicht die Frage, wie genau Entscheidungen getroffen werden. Die grundlegende Antwort ist: Entscheidungen werden per Konsens getroffen, von allen, die sich an der Diskussion im Forum beteiligen möchten. Dazu gehören Entwickler, andere Benutzer und Sie selbst. Das Streben nach Konsens in der Diskussion ist wichtig – SciPy ist ein Projekt von und für die wissenschaftliche Python-Community. In den seltenen Fällen, in denen keine Einigung erzielt werden kann, können die Betreuer des betreffenden Moduls die Frage entscheiden.

Lizenzüberlegungen#

Ich habe meinen Code auf bestehendem Matlab/R/... Code aufgebaut, den ich online gefunden habe. Ist das in Ordnung?

Das hängt davon ab. SciPy wird unter einer BSD-Lizenz vertrieben. Wenn der Code, auf dem Ihr Code basiert, ebenfalls BSD-lizenziert ist oder eine BSD-kompatible Lizenz hat (z. B. MIT, PSF), dann ist das in Ordnung. Code, der unter GPL oder Apache lizenziert ist, keine klare Lizenz hat, eine Zitierung erfordert oder nur für akademische Zwecke kostenlos ist, kann nicht in SciPy aufgenommen werden. Wenn Sie daher bestehenden Code mit einer solchen Lizenz kopiert oder eine direkte Übersetzung davon ins Python-Format vorgenommen haben, kann Ihr Code nicht aufgenommen werden. Wenn Sie unsicher sind, fragen Sie bitte im scipy-dev Forum.

Warum steht SciPy unter der BSD-Lizenz und nicht, sagen wir, unter der GPL?

Wie Python verwendet SciPy eine "permissive" Open-Source-Lizenz, die die proprietäre Wiederverwendung erlaubt. Während dies Unternehmen ermöglicht, die Software zu nutzen und zu modifizieren, ohne etwas zurückgeben zu müssen, wird davon ausgegangen, dass die größere Nutzerbasis zu insgesamt mehr Beiträgen führt und Unternehmen ihre Modifikationen oft ohnehin veröffentlichen, ohne dazu verpflichtet zu sein. Sehen Sie John Hunters BSD-Pitch.

Weitere Informationen zur SciPy-Lizenz finden Sie unter Lizenzierung.

Bestehenden Code pflegen#

Der vorherige Abschnitt befasste sich speziell mit dem Hinzufügen neuer Funktionalitäten zu SciPy. Ein großer Teil dieser Diskussion gilt auch der Pflege bestehenden Codes. Pflege bedeutet, Fehler zu beheben, die Codequalität zu verbessern, bestehende Funktionalität besser zu dokumentieren, fehlende Unit-Tests hinzuzufügen, Performance-Benchmarks hinzuzufügen, Build-Skripte auf dem neuesten Stand zu halten usw. Die SciPy Issue-Liste enthält alle gemeldeten Fehler, Build-/Dokumentationsprobleme usw. Das Beheben von Issues trägt zur Verbesserung der Gesamtqualität von SciPy bei und ist auch eine gute Möglichkeit, sich mit dem Projekt vertraut zu machen. Möglicherweise möchten Sie auch einen Fehler beheben, weil Sie auf ihn gestoßen sind und die betreffende Funktion korrekt funktionieren muss.

Die Diskussion über Code-Stil und Unit-Tests oben gilt gleichermaßen für Fehlerbehebungen. Es ist in der Regel am besten, zuerst einen Unit-Test zu schreiben, der das Problem zeigt, d. h. er sollte funktionieren, aber tut es nicht. Sobald Sie das haben, können Sie den Code reparieren, damit der Test funktioniert. Das sollte ausreichen, um einen PR für dieses Issue zu senden. Im Gegensatz zum Hinzufügen von neuem Code ist es möglicherweise nicht notwendig, dies im Forum zu besprechen – wenn das alte Verhalten des Codes eindeutig falsch ist, wird niemand etwas dagegen haben, wenn es behoben wird. Es kann notwendig sein, eine Warnung oder eine Deprecation-Nachricht für das geänderte Verhalten hinzuzufügen. Dies sollte Teil des Überprüfungsprozesses sein.

Hinweis

Pull-Requests, die *nur* den Code-Stil ändern, z. B. die Behebung einiger PEP8-Probleme in einer Datei, sind nicht erwünscht. Solche PRs sind oft nicht die Mühe wert, die Git-Annotationshistorie zu verstopfen, und beanspruchen Zeit von Prüfern, die besser anderweitig genutzt werden könnte. Code-Stil-Bereinigungen von Code, der als Teil einer funktionalen Änderung berührt wird, sind jedoch in Ordnung.

Pull-Requests prüfen#

Die Überprüfung offener Pull-Requests (PRs) ist sehr willkommen und eine wertvolle Möglichkeit, die Geschwindigkeit, mit der das Projekt vorankommt, zu erhöhen. Wenn Sie über spezifische Kenntnisse/Erfahrungen in einem bestimmten Bereich verfügen (z. B. "Optimierungsalgorithmen" oder "Spezialfunktionen"), ist die Überprüfung von PRs in diesem Bereich besonders wertvoll – manchmal müssen PRs mit technischem Code lange auf die Zusammenführung warten, da es einen Mangel an geeigneten Prüfern gibt.

Wir ermutigen alle, sich am Überprüfungsprozess zu beteiligen; es ist auch eine großartige Möglichkeit, sich mit der Codebasis vertraut zu machen. Prüfer sollten sich einige oder alle der folgenden Fragen stellen

  • Wurde diese Änderung angemessen diskutiert (relevant für neue Funktionen und Änderungen im bestehenden Verhalten)?

  • Ist die Funktion wissenschaftlich fundiert? Algorithmen sind möglicherweise auf der Grundlage von Literatur bekannt; andernfalls ist eine genauere Prüfung der Korrektheit wertvoll.

  • Ist das beabsichtigte Verhalten unter allen Bedingungen klar (z. B. unerwartete Eingaben wie leere Arrays oder NaN/Inf-Werte)?

  • Erfüllt der Code die Qualitäts-, Test- und Dokumentationserwartungen, die unter Neuen Code beisteuern aufgeführt sind?

Wenn wir Sie noch nicht kennen, stellen Sie sich bitte vor.

Andere Wege, beizutragen#

Es gibt viele Möglichkeiten, beizutragen, die nicht das Schreiben von Code betreffen.

Das Triagieren von Issues (Untersuchen von Fehlerberichten auf Gültigkeit und mögliche Maßnahmen) ist ebenfalls eine nützliche Tätigkeit. SciPy hat viele Hunderte offener Issues; das Schließen ungültiger Issues und das korrekte Markieren gültiger Issues (idealerweise mit ersten Gedanken in einem Kommentar) ermöglicht die Priorisierung von Wartungsarbeiten und das einfache Finden verwandter Issues bei der Arbeit an einer bestehenden Funktion oder einem Unterpaket. Weitere Informationen zur Issue-Triage finden Sie unter Issues triagieren und kuratieren.

Die Teilnahme an Diskussionen im scipy-user und scipy-dev Forum ist ein Beitrag für sich. Jeder, der mit einem Problem oder einer Idee an diese Listen schreibt, möchte Antworten erhalten, und das Schreiben solcher Antworten lässt das Projekt und die Community besser funktionieren und einladender erscheinen.

Die scipy.org Website enthält viele Informationen sowohl über SciPy als Projekt als auch über SciPy als Community, und sie könnte immer ein paar neue Hände gebrauchen. Die Quellen für die Website befinden sich in ihrem eigenen separaten Repository: scipy/scipy.org

Erste Schritte#

Vielen Dank für Ihr Interesse an der Mitarbeit bei SciPy! Wenn Sie daran interessiert sind, Code beizusteuern, hoffen wir, dass Sie sich als Nächstes an den SciPy-Leitfaden für Mitwirkende wenden, um Details zu erhalten, wie Sie Ihre Entwicklungsumgebung einrichten, Ihre Verbesserungen implementieren und Ihren ersten PR einreichen!