Continuous Integration#

Kontinuierliche Integration (CI) ist Teil unseres Entwicklungsprozesses und stellt sicher, dass jeder Code- oder Dokumentationsbeitrag zu SciPy funktioniert und keine unvorhergesehenen Auswirkungen hat.

Hinweis

Stellen Sie vor dem Einreichen oder Aktualisieren Ihres PR sicher, dass Sie Ihre Änderungen lokal getestet haben. Siehe Checkliste vor dem Einreichen eines PR und SciPy-Tests lokal ausführen.

Workflows#

Wir führen über 20 verschiedene Workflows mit unterschiedlichen Versionen der Abhängigkeiten, verschiedenen Architekturen usw. durch. Ein PR muss alle diese Prüfungen bestehen, bevor er zusammengeführt werden kann, um einen nachhaltigen Zustand des Projekts zu gewährleisten.

Neben den Unit-Tests werden auch die Dokumentation und Beispiele in den Docstrings überprüft. Dies sind häufig fehlschlagende Workflows, da Sphinx und Doctests sehr strenge Regeln haben. Diese Aspekte sind sehr wichtig, da Dokumentation und Beispiele benutzersichtbare Elemente sind. Stellt sicher, dass diese Elemente korrekt gerendert werden.

Die Protokolle können lang sein, aber Sie werden immer herausfinden, warum Ihr Build/Test eine Prüfung nicht bestanden hat. Klicken Sie einfach auf Details, um auf die Protokolle zuzugreifen.

Im Folgenden finden Sie eine Liste aller verschiedenen verwendeten Workflows. Sie sind nach CI-Ressourcenanbietern gruppiert.

GitHub Actions#

  • Lint: PEP8 und Code-Stil

  • Windows Tests: Testsuite für Windows

  • Linux Tests: Testsuite für Linux

  • macOS Tests: Testsuite für macOS (x86_64)

  • Wheels builder: Erstellt Wheels für SciPy-Releases sowie für *nächtliche* Builds.

  • Check the rendered docs here!: Live-Vorschau der Dokumentation

  • prerelease_deps_coverage_64bit_blas: Verwendet Vorabversionen der Abhängigkeiten und prüft die Abdeckung

  • gcc-9: Baut mit minimal unterstützter GCC-Version, installiert das Wheel, dann wird die Testsuite mit python -OO ausgeführt

  • Array API: Testet die Unterstützung der Array-API

Die Testsuite läuft auf GitHub Actions und anderen Plattformen unter einer Reihe von Test-/Umgebungsbedingungen: Python- und NumPy-Versionen (von der niedrigsten unterstützten bis zu nächtlichen Builds), 32-Bit vs. 64-Bit, verschiedene Compiler und mehr – Details finden Sie in den .yml-Konfigurationsdateien.

CircleCI#

  • build_docs: Erstellt die Dokumentation

  • build_scipy

  • run_benchmarks: Überprüft, wie sich die Änderungen auf die Leistung auswirken

  • refguide_check: Doctests aus Beispielen und Benchmarks

Überspringen#

Als Open-Source-Projekt haben wir Zugriff auf ein Kontingent an CI-Ressourcen. Letztendlich sind die Ressourcen begrenzt und wir sollten sie mit Bedacht einsetzen. Deshalb bitten wir Sie, Ihre Änderungen vor dem Pushen lokal zu überprüfen.

Abhängig von der vorgeschlagenen Änderung möchten Sie möglicherweise Teile der Prüfungen überspringen. Es liegt im Ermessen eines Maintainers, einige Tests vor der Integration erneut auszuführen.

Das Überspringen von CI kann durch Hinzufügen eines speziellen Textes zur Commit-Nachricht erreicht werden

  • [skip actions]: überspringt GitHub Actions

  • [skip circle]: überspringt CircleCI

  • [docs only]: überspringt *alle bis auf* die CircleCI-Prüfungen und den Linter

  • [lint only]: überspringt *alle bis auf* den Linter

  • [skip ci]: überspringt *alle* CI

Sie können diese natürlich kombinieren, um mehrere Workflows zu überspringen.

Diese Skip-Informationen sollten in einer neuen Zeile platziert werden. In diesem Beispiel haben wir nur eine .rst-Datei in der Dokumentation aktualisiert und darum gebeten, alle außer den relevanten Dokumentationsprüfungen zu überspringen (GitHub Actions-Workflows überspringen)

DOC: improve QMCEngine examples.

[docs only]

Fehler aufgrund von Testdauer#

Einige CI-Jobs installieren pytest-fail-slow und melden Fehler, wenn die Testausführungszeit einen Schwellenwert überschreitet.

  • Standardmäßig unterliegen alle Tests einer Grenze von 5 Sekunden; d. h. die Option --fail-slow=5.0 wird in einem "vollen" Testjob verwendet.

  • Alle Tests, die nicht mit slow (@pytest.mark.slow) markiert sind, unterliegen einer Grenze von 1 Sekunde; d. h. die Option --fail-slow=1.0 wird in einem "schnellen" Testjob verwendet.

  • Ausnahmen werden mit dem Dekorator pytest.mark.fail_slow gemacht; z. B. kann ein Test mit @pytest.mark.fail_slow(10) markiert werden, um ihm eine zehn Sekunden lange Grenze zu geben, unabhängig davon, ob er Teil der "schnellen" oder "vollen" Testsuite ist.

Wenn ein Test während der Entwicklung eines PR durch Überschreitung des Zeitlimits fehlschlägt, passen Sie den Test bitte so an, dass er in Zukunft nicht mehr fehlschlägt. Auch wenn neue Tests nicht fehlschlagen, überprüfen Sie bitte die Details der Workflows, die "fail slow" in ihrem Namen enthalten, bevor PRs zusammengeführt werden. Diese enthalten Listen von Tests, die sich der Zeitgrenze nähern (oder sie überschritten haben). Aufgrund von Variationen in der Ausführungszeit sollten Tests mit Ausführungszeiten nahe dem Schwellenwert so angepasst werden, dass sie auch dann nicht fehlschlagen, wenn ihre Ausführungszeit um 50 % steigt; typische Tests sollten eine viel größere Marge haben (mindestens 400 %). Anpassungsoptionen umfassen

  • Den Test schneller machen.

  • Den Test als slow markieren, wenn es akzeptabel ist, den Test auf einer reduzierten Anzahl von Plattformen auszuführen.

  • Den Test als xslow markieren, wenn es akzeptabel ist, den Test nur gelegentlich auszuführen.

  • Den Test aufteilen oder parametrisieren und möglicherweise Teile davon als langsam markieren. Beachten Sie, dass dies die Gesamttestdauer nicht verkürzt, daher sind andere Optionen vorzuziehen.

  • Für wirklich kritische Tests, die unvermeidlich langsam sind, fügen Sie eine Ausnahme mit pytest.mark.fail_slow hinzu.

Weitere Informationen zur Arbeit mit langsamen Tests lokal finden Sie unter SciPy-Tests lokal ausführen.

Wheel-Builds#

Wheels für SciPy-Releases und *nächtliche* Builds werden mit cibuildwheel in einer GitHub Action erstellt. Die Aktion wird ausgeführt

  • wenn die Commit-Nachricht den Text [wheel build] enthält

  • auf geplante Basis einmal pro Woche

  • wenn sie manuell gestartet wird.

  • wenn es einen Push zum Repository mit einer GitHub-Referenz gibt, die mit refs/tags/v beginnt (und nicht mit dev0 endet)

Die Aktion wird nicht auf Forks des Haupt-SciPy-Repositorys ausgeführt. Die erstellten Wheels sind als Artefakte verfügbar, die mit einer erfolgreichen Ausführung der Aktion verbunden sind. Wenn die Aktion geplant ausgeführt wird oder manuell gestartet wird, werden die Wheels in das Repository *scientific-python-nightly-wheels* hochgeladen.

Es wird nicht empfohlen, cibuildwheel zum Erstellen von SciPy-Wheels auf Ihrem eigenen System zu verwenden, da es automatisch gfortran-Compiler und verschiedene andere Abhängigkeiten installiert. Stattdessen könnte man einen isolierten Docker-Container zum Erstellen von Linux-Wheels verwenden.