Freigabeleitfaden Nr.

Dieses Dokument ist nur für Matplotlib-Release-Manager relevant.

Ein Leitfaden für Entwickler, die eine Matplotlib-Veröffentlichung durchführen.

Notiz

Dies setzt voraus, dass es sich um eine Nur-Lese-Fernbedienung für das kanonische Repository remoteund eine Lese-/Schreib-Remote handeltDANGER

Test #

Wir verwenden GitHub Actions für kontinuierliche Integration. Bei der Vorbereitung auf eine Veröffentlichung sollte der endgültige getaggte Commit lokal getestet werden, bevor er hochgeladen wird:

pytest -n 8 .

Zusätzlich sollte der folgende Test durchgeführt und manuell überprüft werden:

python tools/memleak.py agg 1000 agg.pdf

Darüber hinaus sollte Folgendes ausgeführt und manuell überprüft werden, ist jedoch derzeit defekt:

pushd examples/tests/
python backend_driver_sgskip.py
popd

GitHub-Statistik #

Wir extrahieren automatisch GitHub-Probleme, PRs und Autoren von GitHub über die API. Kopieren Sie die aktuelle doc/users/github_stats.rstnach doc/users/prev_whats_new/github_stats_X.Y.Z.rst, ändern Sie das Linkziel am Anfang der Datei und entfernen Sie den Abschnitt „Previous GitHub Stats“ am Ende.

Zum Beispiel beim Update von v3.2.0 auf v3.2.1:

cp doc/users/github_stats.rst doc/users/prev_whats_new/github_stats_3.2.0.rst
$EDITOR doc/users/prev_whats_new/github_stats_3.2.0.rst
# Change contents as noted above.
git add doc/users/prev_whats_new/github_stats_3.2.0.rst

Generieren Sie dann die aktualisierten Statistiken neu:

python tools/github_stats.py --since-tag v3.2.0 --milestone=v3.2.1 --project 'matplotlib/matplotlib' --links > doc/users/github_stats.rst

Änderungen überprüfen und festschreiben. Einige Ausgabe-/PR-Titel sind möglicherweise kein gültiges reST (das häufigste Problem wird *als nicht geschlossenes Markup interpretiert).

Notiz

Stellen Sie sicher, dass Sie sich bei der GitHub-API authentifizieren. Wenn Sie dies nicht tun, werden Sie von GitHub blockiert, weil Sie die API-Ratenlimits überschreiten. Sie können sich auf zwei Arten authentifizieren:

  • Verwenden des keyringPakets; und dann, wenn Sie das Statistikskript ausführen, werden Sie zur Eingabe von Benutzername und Passwort aufgefordert, die in Ihrem Systemschlüsselbund gespeichert werden, oderpip install keyring

  • Verwenden eines persönlichen Zugriffstokens; Generieren Sie auf dieser GitHub-Seite ein neues Token mit dem repo:public_repo Bereich und platzieren Sie das Token in ~/.ghoauth.

Aktualisieren und validieren Sie die Dokumente #

Filiale *-doczusammenführen #

Führen Sie den neuesten 'doc'-Zweig (z. B. v3.2.0-doc) mit dem Zweig zusammen, den Sie markieren möchten, und löschen Sie den doc-Zweig auf GitHub.

Aktualisieren Sie unterstützte Versionen in der Sicherheitsrichtlinie #

Aktualisieren Sie beim Erstellen von Haupt- oder Nebenversionen die unterstützten Versionen in der Sicherheitsrichtlinie in SECURITY.md. In der Regel können dies ein oder zwei frühere Nebenversionen sein, dies hängt jedoch von den Versionsmanagern ab.

Versionshinweise aktualisieren #

Was ist neu #

Nur für Major- und Minor-Releases erforderlich. Bugfix-Releases sollten keine neuen Funktionen enthalten.

Führen Sie den Inhalt aller Dateien doc/users/next_whats_new/ in einer einzigen Datei doc/users/prev_whats_new/whats_new_X.Y.0.rst zusammen und löschen Sie die einzelnen Dateien.

API-Änderungen #

Wird hauptsächlich für Haupt- und Nebenversionen benötigt. Wir können manchmal API-Änderungen in Bugfix-Releases haben.

Führen Sie den Inhalt aller Dateien doc/api/next_api_changes/ in einer einzigen Datei doc/api/prev_api_changes/api_changes_X.Y.Z.rst zusammen und löschen Sie die einzelnen Dateien.

Versionshinweise Inhaltsverzeichnis Nr .

Aktualisieren doc/users/release_notes.rst:

  • Fügen Sie für Haupt- und Nebenversionen einen neuen Abschnitt hinzu

    X.Y
===
.. toctree::
    :maxdepth: 1

    prev_whats_new/whats_new_X.Y.0.rst
    ../api/prev_api_changes/api_changes_X.Y.0.rst
    prev_whats_new/github_stats_X.Y.0.rst

  • Fügen Sie für Bugfix-Releases die GitHub-Statistiken und (falls vorhanden) die API-Änderungen zum bestehenden XY-Abschnitt hinzu

    ../api/prev_api_changes/api_changes_X.Y.Z.rst
prev_whats_new/github_stats_X.Y.Z.rst

Versionsumschalter # aktualisieren

Aktualisieren doc/_static/switcher.json. Wenn es sich um eine Nebenversion handelt X.Y.Z, erstellen Sie einen neuen Eintrag und ändern Sie den Namen von stable . Wenn es sich um eine Hauptversion handelt , ändern Sie den Namen von und und fügen Sie eine neue Version für die vorherige Stable hinzu.version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

Überprüfen Sie, ob die Dokument-Build- Nr .

Stellen Sie schließlich sicher, dass die Dokumente sauber erstellt werden

make -Cdoc O=-j$(nproc) html latexpdf

Überprüfen Sie nach dem Erstellen der Dokumente, ob alle internen und externen Links noch gültig sind. Wir verwenden linkcheckerdafür, das noch nicht auf Python3 portiert wurde. Sie müssen eine Python2-Umgebung mit einem Linkchecker requests==2.9.0erstellen

conda create -p /tmp/lnkchk python=2 requests==2.9.0
source activate /tmp/lnkchk
pip install linkchecker
pushd doc/build/html
linkchecker index.html --check-extern
popd

Gehen Sie auf eventuell auftretende Probleme ein. Die internen Links werden auf Circle CI überprüft, dies sollte nur fehlerhafte externe Links kennzeichnen.

Aktualisieren Sie unterstützte Versionen in SECURITY.md #

Aktualisieren Sie für Nebenversionsversionen die Tabelle in SECURITY.md, um anzugeben, dass die 2 neuesten Nebenversionen in der aktuellen Hauptversionsserie unterstützt werden.

Aktualisieren Sie für eine Hauptversionsversion die Tabelle in SECURITY.md, um anzugeben, dass die letzte Nebenversion in der vorherigen Hauptversionsreihe weiterhin unterstützt wird. Die Einstellung des Supports für die letzte Version einer Hauptversionsreihe erfolgt auf Ad-hoc-Basis.

Release-Commit und -Tag erstellen #

Um das Tag zu erstellen, erstellen Sie zunächst einen leeren Commit mit einem sehr knappen Satz der Versionshinweise in der Commit-Nachricht

git commit --allow-empty

und erstellen Sie dann ein signiertes, kommentiertes Tag mit demselben Text in der Textnachricht

git tag -a -s v2.0.0

Dadurch werden Sie zur Eingabe Ihres GPG-Schlüsselkennworts und einer Anmerkung aufgefordert. Für Vorabversionen ist es wichtig, zu folgenPEP 440 , damit die Build-Artefakte in PyPI korrekt sortiert werden.

Um Probleme mit Downstream-Buildern zu vermeiden, die den Tarball von GitHub herunterladen, ist es wichtig, alle Branches mit dem Tag [ 1 ] vom Commit wegzubewegen :

git commit --allow-empty

Pushen Sie schließlich das Tag zu GitHub:

git push DANGER main v2.0.0

Herzlichen Glückwunsch, der gruseligste Teil ist geschafft!

Wenn es sich um eine endgültige Version handelt, erstellen Sie auch einen „Doc“-Zweig (dies wird bei Vorabversionen nicht durchgeführt):

git branch v2.0.0-doc
git push DANGER v2.0.0-doc

und wenn es sich um eine Haupt- oder Nebenversion handelt, erstellen Sie auch einen Bugfix-Zweig (eine Mikroversion wird aus diesem Zweig herausgeschnitten):

git branch v2.0.x

Kommentieren Sie in diesem Zweig die Globs von Update aus und validieren Sie die Dokumente . Und dann

git push DANGER v2.0.x

Freigabemanagement / DOI #

Verwandeln Sie das neu gepushte Tag über die GitHub -Benutzeroberfläche in ein Release. Wenn es sich um eine Vorabversion handelt, denken Sie daran, sie als solche zu kennzeichnen.

Holen Sie sich für endgültige Veröffentlichungen auch den DOI von zenodo (der automatisch einen erstellt, sobald das Tag gepusht wird). Fügen Sie das DOI-Postfix und die Version zum Wörterbuch hinzu tools/cache_zenodo_svg.pyund führen Sie das Skript aus.

Dadurch wird das neue SVG in das _staticVerzeichnis in den Dokumenten heruntergeladen und bearbeitet doc/citing.rst. Übertragen Sie das neue SVG, die Änderung an tools/cache_zenodo_svg.pyund die Änderungen an doc/citing.rstin den VER-doc-Zweig und übertragen Sie ihn auf GitHub.

git checkout v2.0.0-doc
$EDITOR tools/cache_zenodo_svg.py
python tools/cache_zenodo_svg.py
$EDITOR doc/citing.html
git commit -a
git push DANGER v2.0.0-doc:v2.0.0-doc

Erstellen von Binärdateien #

Wir vertreiben macOS, Windows und viele Linux-Räder sowie einen Quell-Tarball über PyPI. Die meisten Builder sollten automatisch ausgelöst werden, sobald das Tag an GitHub übertragen wird:

  • Windows, macOS und viele Linux-Wheels basieren auf GitHub Actions. Builds werden durch die in definierte GitHub-Aktion ausgelöst .github/workflows/cibuildwheel.yml, und Räder sind als Artefakte des Builds verfügbar.

  • Alternative Windows-Räder werden von Christoph Gohlke automatisch erstellt und nach dem Erstellen auf seiner Website verfügbar sein .

  • Der Auto-Tick-Bot sollte eine Pull-Anfrage in den Conda-Forge-Feedstock öffnen . Überprüfen und zusammenführen (wenn Sie die Befugnis dazu haben).

Warnung

Da dies automatisiert ist, ist es äußerst wichtig, alle Branches vom Tag wegzustoßen, wie in Release-Commit und -Tag erstellen beschrieben .

Wenn es sich um eine endgültige Version handelt, sollten die folgenden nachgeschalteten Paketierer kontaktiert werden:

  • Debian

  • Fedora

  • Bogen

  • Gentoo

  • Macports

  • Hausgemacht

  • Kontinuum

  • Nachgedacht

Dies kann vor dem Sammeln aller Binärdateien und dem Hochladen auf pypi erfolgen.

Verteilung vornehmen und auf PyPI hochladen #

Wenn Sie alle Räder eingesammelt haben (was ungefähr einen Tag dauern wird), generieren Sie den Tarball

git checkout v2.0.0
git clean -xfd
python setup.py sdist

und kopieren Sie alle Räder in das distVerzeichnis. Überprüfen Sie zunächst, ob die dist-Dateien in Ordnung sind

twine check dist/*

und verwenden Sie dann twine, um alle Dateien auf pypi hochzuladen

twine upload -s dist/matplotlib*tar.gz
twine upload dist/*whl

Herzlichen Glückwunsch, Sie haben jetzt den zweitgruseligsten Teil geschafft!

Dokumentation erstellen und bereitstellen #

Um die Dokumentation zu erstellen, müssen Sie die getaggte Version installiert haben, aber erstellen Sie die Dokumentation aus dem ver-docZweig. Eine einfache Möglichkeit, dies zu arrangieren, ist:

pip install matplotlib
pip install -r requirements/doc/doc-requirements.txt
git checkout v2.0.0-doc
git clean -xfd
make -Cdoc O="-t release -j$(nproc)" html latexpdf LATEXMKOPTS="-silent -f"

die sowohl die HTML- als auch die PDF-Version der Dokumentation erstellt.

Die erstellte Dokumentation befindet sich im Repository matplotlib.github.com . Durch Pushen von Änderungen an main wird die Website automatisch aktualisiert.

Die Dokumentation ist nach Version geordnet. An der Wurzel des Baums befindet sich immer die Dokumentation für die neueste stabile Version. Darunter befinden sich Verzeichnisse mit der Dokumentation für ältere Versionen. Die Dokumentation für Current Main basiert auf Circle CI und wird in das devdocs- Repository verschoben. Diese sind unter matplotlib.org/devdocs verfügbar .

Angenommen, Sie haben dieses Repository im selben Verzeichnis wie matplotlib ausgecheckt

cd ../matplotlib.github.com
mkdir 2.0.0
rsync -a ../matplotlib/doc/build/html/* 2.0.0
cp ../matplotlib/doc/build/latex/Matplotlib.pdf 2.0.0

wodurch die erstellten Dokumente kopiert werden. Wenn es sich um eine endgültige Version handelt, verknüpfen Sie das stableUnterverzeichnis mit der neuesten Version:

rsync -a 2.0.0/* ./
rm stable
ln -s 2.0.0/ stable

Sie müssen manuell bearbeiten versions.html, um die letzten 3 getaggten Versionen anzuzeigen. Sie müssen auch bearbeiten sitemap.xml, um die neu veröffentlichte Version aufzunehmen. Committen und pushen Sie jetzt alles auf GitHub

git add *
git commit -a -m 'Updating docs for v2.0.0'
git push DANGER main

Herzlichen Glückwunsch, Sie haben jetzt den drittgruseligsten Teil geschafft!

Wenn Sie Zugriff haben, löschen Sie die Cloudflare-Caches.

Es dauert in der Regel etwa 5–10 Minuten, bis GitHub den Push verarbeitet und die Live-Webseite aktualisiert (denken Sie daran, Ihren Browser-Cache zu löschen).

Ankündigung #

Der letzte Schritt besteht darin, die Veröffentlichung der Welt bekannt zu geben. Eine kurze Version der Versionshinweise zusammen mit Danksagungen sollte an gesendet werden

Für endgültige Veröffentlichungen sollten Ankündigungen auch an die Mailinglisten numpy/scipy/scikit-image gesendet werden.

Außerdem sollten Ankündigungen in sozialen Netzwerken (Twitter über den @matplotlibAccount, alle anderen über persönliche Accounts) erfolgen. NumFOCUS sollte für die Aufnahme in ihren Newsletter kontaktiert werden.

Conda-Pakete #

Das Matplotlib-Projekt selbst veröffentlicht keine Conda-Pakete. Insbesondere ist der Matplotlib-Release-Manager nicht für die Conda-Paketierung verantwortlich.

Informationen zur Paketierung von Matplotlib für conda-forge finden Sie unter https://github.com/conda-forge/matplotlib-feedstock .