Development workflow#

Hinweis: Sehen Sie sich die Aufzeichnung SciPy Development Workflow vor oder nach dem Lesen an, um ein Beispiel für die Behebung eines Fehlers und die Einreichung eines Pull-Requests zu sehen.

Diese Anleitung setzt voraus, dass Sie eine eigene Abspaltung (Kopie) des SciPy-Repositorys erstellt, das Repository auf Ihrem eigenen Rechner geklont und SciPy aus diesem Quellcode erstellt haben. Falls nicht, lesen Sie die Seiten zum Thema Bauen aus dem Quellcode, die für Ihr System relevant sind. Bevor Sie hier beginnen, gibt es noch zwei Dinge, die Sie nur einmal tun müssen, bevor Sie mit der Änderung von SciPy beginnen.

  1. Stellen Sie sich in einem Terminal bei Git vor

    git config --global user.email you@yourdomain.com
git config --global user.name "Your Name"

    Diese Informationen schreiben Ihnen Ihre Arbeit gut, aber beachten Sie, dass sie öffentlich zugänglich werden, wenn Sie Ihre Arbeit auf GitHub „pushen“. Weitere Informationen finden Sie unter Einstellung Ihrer Commit-E-Mail-Adresse in Git.

  2. Navigieren Sie in das Stammverzeichnis Ihres lokalen SciPy-Repositorys und geben Sie ein

    git remote add upstream https://github.com/scipy/scipy.git

    Dies ordnet dem Namen upstream das offizielle SciPy-Repository unter scipy/scipy.git zu. Beachten Sie, dass Git beim Klonen Ihrer Abspaltung des SciPy-Repositorys bereits den Namen origin mit Ihrer Abspaltung verknüpft hat. Der Grund für die Notwendigkeit beider dieser „Remotes“ ist, dass Sie normalerweise mit der neuesten Version von SciPy aus dem offiziellen Repository upstream beginnen, Änderungen vornehmen, Ihre Änderungen in Ihre Abspaltung des Repositorys origin „pushen“ und dann einen „Pull-Request“ einreichen, der SciPy bittet, Ihre Änderungen von Ihrer Abspaltung in das offizielle Repository zu „pullen“.

  3. Git-Submodule initialisieren

    git submodule update --init

    Dies ruft und aktualisiert alle Submodule ab, die SciPy benötigt (z. B. Boost).

Grundlegender Workflow#

Kurz gesagt

  1. Starten Sie für jeden Satz von Änderungen, den Sie vornehmen, einen neuen Feature-Branch. Siehe unten.

  2. Hacken Sie drauf los! Siehe unten.

  3. Wenn fertig

    • Mitwirkende: Pushen Sie Ihren Feature-Branch in Ihr eigenes Github-Repo und erstellen Sie einen Pull-Request.

    • Kernentwickler Wenn Sie Änderungen ohne weitere Überprüfung pushen möchten, lesen Sie die Hinweise unten.

Diese Arbeitsweise hilft, die Arbeit gut organisiert und die Historie so klar wie möglich zu halten.

Siehe auch

Es gibt viele Online-Tutorials, die Ihnen helfen, Git zu lernen. Diskussionen zu spezifischen Git-Workflows finden Sie in diesen Diskussionen zu linux git workflow und ipython git workflow.

Erstellen eines neuen Feature-Branches#

Navigieren Sie zunächst im Terminal zum Stammverzeichnis von SciPy und rufen Sie neue Commits aus dem upstream-Repository ab

git fetch upstream

Erstellen Sie dann einen neuen Branch basierend auf dem Hauptbranch des Upstream-Repositorys

git checkout -b my-new-feature upstream/main

Alternativ können Sie den Hauptbranch Ihres eigenen Repositorys auf dem neuesten Stand halten und einen neuen Branch darauf basierend erstellen

git checkout main
git rebase upstream/main
git checkout -b my-new-feature

In dieser Reihenfolge diese Befehle

  1. stellen Sie sicher, dass der main-Branch Ihres lokalen Repositorys ausgecheckt ist,

  2. wenden Sie alle neuesten Änderungen von upstream/main (Haupt-Branch des Haupt-SciPy-Repositorys) auf Ihren lokalen main-Branch an, und

  3. erstellen und checken Sie einen neuen Branch (-b) basierend auf Ihrem lokalen main-Branch aus.

In jedem Fall ist es wichtig, dass Ihr Feature-Branch die neuesten Änderungen vom Upstream-Main enthält, um Merge-Konflikte zu vermeiden, wenn es Zeit ist, einen Pull-Request einzureichen.

Es ist auch ratsam, diesen Branch zu erstellen und Tests auszuführen, bevor Sie fortfahren. Vorausgesetzt, Sie haben eine der Seiten unter Bauen aus dem Quellcode befolgt, um Ihre Entwicklungsumgebung einzurichten, müssen Sie Ihre Entwicklungsumgebung aktivieren und dann Tests ausführen (beachten Sie, dass der Befehl dev.py test automatisch einen Build durchführt, falls erforderlich)

conda activate scipy-dev
python dev.py test -v

Der Editing-Workflow#

Überblick#

# hack hack
git status # Optional
git diff # Optional
git add modified_file
git commit
# push the branch to your own Github repo
git push origin my-new-feature

Im Detail#

  1. Nehmen Sie einige Änderungen vor. Wenn Sie das Gefühl haben, eine vollständige, funktionierende Reihe zusammenhängender Änderungen vorgenommen zu haben, fahren Sie mit den nächsten Schritten fort.

  2. Optional: Überprüfen Sie, welche Dateien sich mit git status geändert haben (siehe git status). Sie sehen eine Auflistung wie diese

    # On branch my-new-feature
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   README
#
# Untracked files:
#   (use "git add <file>..." to include in what will be committed)
#
#  INSTALL
no changes added to commit (use "git add" and/or "git commit -a")

  3. Optional: Vergleichen Sie die Änderungen mit der vorherigen Version mit git diff (git diff). Dies öffnet eine einfache Textbrowser-Oberfläche, die die Unterschiede zwischen Ihren Dateien und der vorherigen Version hervorhebt.

  4. Fügen Sie alle relevanten geänderten oder neuen Dateien mit git add geänderte_datei hinzu (siehe git add). Dies legt die Dateien in einen Staging-Bereich, eine Warteschlange von Dateien, die in Ihren nächsten Commit aufgenommen werden. Fügen Sie nur Dateien hinzu, die zusammenhängende, vollständige Änderungen aufweisen. Lassen Sie Dateien mit unvollständigen Änderungen für spätere Commits.

  5. Um die gestageten Dateien in die lokale Kopie Ihres Repos zu committen, führen Sie git commit aus. An diesem Punkt öffnet sich ein Texteditor, der es Ihnen ermöglicht, eine Commit-Nachricht zu schreiben. Lesen Sie den Abschnitt Commit-Nachricht, um sicherzustellen, dass Sie eine ordnungsgemäß formatierte und ausreichend detaillierte Commit-Nachricht schreiben. Nach dem Speichern Ihrer Nachricht und dem Schließen des Editors wird Ihr Commit gespeichert. Für triviale Commits kann eine kurze Commit-Nachricht über die Befehlszeile mit dem Flag -m übergeben werden. Zum Beispiel: git commit -am "ENH: Einige Nachricht".

    In einigen Fällen sehen Sie diese Form des Commit-Befehls: git commit -a. Das zusätzliche Flag -a committet automatisch alle geänderten Dateien und entfernt alle gelöschten Dateien. Dies kann Ihnen Tipparbeit für zahlreiche git add-Befehle ersparen; es kann jedoch unerwünschte Änderungen in einen Commit aufnehmen, wenn Sie nicht vorsichtig sind. Weitere Informationen finden Sie unter Warum das -a Flag? – und der hilfreichen Beschreibung von Anwendungsfällen im Problem des verworrenen Arbeitskopie-Problems.

  6. Pushen Sie die Änderungen in Ihr gespiegeltes Repo auf GitHub

    git push origin my-new-feature

    Weitere Informationen finden Sie unter git push.

Hinweis

Wenn Sie die Anweisungen auf diesen Seiten befolgt haben, erstellt Git einen Standardlink zu Ihrem GitHub-Repo namens origin. In Git >= 1.7 können Sie sicherstellen, dass der Link zu origin dauerhaft gesetzt ist, indem Sie die Option --set-upstream verwenden

git push --set-upstream origin my-new-feature

Von nun an weiß Git, dass mein-neuer-feature mit dem Branch mein-neuer-feature in Ihrem eigenen GitHub-Repo zusammenhängt. Nachfolgende Push-Aufrufe werden dann wie folgt vereinfacht:

git push

Sie müssen --set-upstream für jeden neu erstellten Branch verwenden.

Es kann sein, dass, während Sie an Ihren Änderungen arbeiteten, neue Commits zu upstream hinzugefügt wurden, die Ihre Arbeit beeinflussen. Befolgen Sie in diesem Fall die Anweisungen unter Rebasing auf Main, um diese Änderungen auf Ihren Branch anzuwenden.

Schreiben der Commit-Nachricht#

Commit-Nachrichten sollten klar sein und einige grundlegende Regeln befolgen.

Beispiel

MAINT/TST: fft: remove xp backend skips, test `fftfreq` `device`

The first line of the commit message starts with a capitalized acronym
(or multiple, options listed below) indicating what type of commit this is.
Then a blank line, then more text if needed.
References to code names should be enclosed in backticks.
If changes are limited to certain submodules or functions, they should be
included after the acronym(s) - backticks are not needed here.

Beispiel

BUG:sparse.linalg.gmres: add early exit when `x0` already solves problem

Lines shouldn't be longer than 72 characters. If the commit is related to an issue,
indicate that with "See gh-3456", "Closes gh-3456", or similar,
in the extended description.
However, if you are pushing many commits to a PR, you should avoid including
this in every commit message as it will clutter the linked issue.

Die Beschreibung der Motivation für eine Änderung, die Art eines Fehlers bei Fehlerbehebungen oder einige Details darüber, was eine Verbesserung bewirkt, sind ebenfalls gute Ergänzungen zu einer Commit-Nachricht. Nachrichten sollten ohne Betrachtung der Code-Änderungen verständlich sein. Eine Commit-Nachricht wie MAINT: einen weiteren behoben ist ein Beispiel dafür, was man nicht tun sollte; der Leser muss den Kontext anderswo suchen.

Standardmäßige Akronyme zum Beginn der Commit-Nachricht sind

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building SciPy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing SciPy

Hinweis

Sie können einige Markierungen hinzufügen, um Teile der kontinuierlichen Integration zu überspringen. Siehe Continuous Integration.

Anfordern des Zusammenführens Ihrer Änderungen mit dem Haupt-Repository#

Wenn Sie der Meinung sind, dass Ihre Arbeit abgeschlossen ist, können Sie einen Pull-Request (PR) erstellen. GitHub hat eine hilfreiche Seite, die den Prozess für Einreichen von Pull-Requests beschreibt.

Wenn Ihre Änderungen Modifikationen an der API oder die Hinzufügung/Änderung einer Funktion beinhalten, sollten Sie eine Code-Überprüfung einleiten. Dies beinhaltet das Senden einer E-Mail an das SciPy-Forum mit einem Link zu Ihrem PR sowie einer Beschreibung und Motivation für Ihre Änderungen.

Checkliste vor dem Einreichen eines PR#