Guide de publication #

Ce document n'est pertinent que pour les gestionnaires de versions Matplotlib.

Un guide pour les développeurs qui font une version Matplotlib.

Noter

Cela suppose qu'une télécommande en lecture seule pour le référentiel canonique est remoteet qu'une télécommande en lecture/écriture estDANGER

Test #

Nous utilisons GitHub Actions pour une intégration continue. Lors de la préparation d'une version, le commit balisé final doit être testé localement avant d'être téléchargé :

pytest -n 8 .

De plus, le test suivant doit être exécuté et inspecté manuellement :

python tools/memleak.py agg 1000 agg.pdf

En outre, les éléments suivants doivent être exécutés et inspectés manuellement, mais sont actuellement défectueux :

pushd examples/tests/
python backend_driver_sgskip.py
popd

Statistiques GitHub #

Nous extrayons automatiquement le problème GitHub, les PR et les auteurs de GitHub via l'API. Copiez le courant doc/users/github_stats.rstvers doc/users/prev_whats_new/github_stats_X.Y.Z.rst, en changeant la cible du lien en haut du fichier et en supprimant la section "Previous GitHub Stats" à la fin.

Par exemple, lors de la mise à jour de la v3.2.0 vers la 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

Ensuite, générez à nouveau les statistiques mises à jour :

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

Examinez et validez les modifications. Certains titres de problème/PR peuvent ne pas être valides reST (le problème le plus courant est *celui qui est interprété comme un balisage non fermé).

Noter

Assurez-vous de vous authentifier auprès de l'API GitHub. Si vous ne le faites pas, vous serez bloqué par GitHub pour avoir dépassé les limites de débit de l'API. Vous pouvez vous authentifier de deux manières :

  • utiliser le keyringforfait ; puis lors de l'exécution du script de statistiques, vous serez invité à entrer un nom d'utilisateur et un mot de passe, qui seront stockés dans votre trousseau de clés système, ou,pip install keyring

  • utiliser un jeton d'accès personnel ; générer un nouveau jeton sur cette page GitHub avec la repo:public_repo portée et placer le jeton dans ~/.ghoauth.

Mettre à jour et valider les docs #

Fusionner *-docla branche #

Fusionnez la branche 'doc' la plus récente (par exemple, v3.2.0-doc) dans la branche sur laquelle vous allez marquer et supprimez la branche doc sur GitHub.

Mettre à jour les versions prises en charge dans la politique de sécurité #

Lors de la création de versions majeures ou mineures, mettez à jour les versions prises en charge dans la politique de sécurité dans SECURITY.md. Généralement, il peut s'agir d'une ou deux versions mineures précédentes, mais cela dépend des gestionnaires de version.

Mettre à jour les notes de version #

Quoi de neuf #

Nécessaire uniquement pour les versions majeures et mineures. Les versions de correction de bogues ne doivent pas avoir de nouvelles fonctionnalités.

Fusionnez le contenu de tous les fichiers doc/users/next_whats_new/ dans un seul fichier doc/users/prev_whats_new/whats_new_X.Y.0.rst et supprimez les fichiers individuels.

Modifications de l'API #

Principalement nécessaire pour les versions majeures et mineures. Nous pouvons parfois avoir des changements d'API dans les versions de correction de bogues.

Fusionnez le contenu de tous les fichiers doc/api/next_api_changes/ dans un seul fichier doc/api/prev_api_changes/api_changes_X.Y.Z.rst et supprimez les fichiers individuels.

Notes de version TOC #

Mise à jour doc/users/release_notes.rst:

  • Pour les versions majeures et mineures, ajoutez une nouvelle section

    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

  • Pour les versions de correction de bogues, ajoutez les statistiques GitHub et (le cas échéant) les modifications de l'API à la section XY existante

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

Mettre à jour le sélecteur de version #

Mettre à jour doc/_static/switcher.json. S'il s'agit d'une version mineure X.Y.Z, créez une nouvelle entrée et modifiez le nom de stable . S'il s'agit d'une version majeure , changez le nom de et ajoutez une nouvelle version pour la version stable précédente.version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

Vérifiez que docs build #

Enfin, assurez-vous que les docs se construisent proprement

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

Une fois les documents créés, vérifiez que tous les liens, internes et externes, sont toujours valides. Nous utilisons linkcheckerpour cela, qui n'a pas encore été porté sur Python3. Vous devrez créer un environnement Python2 avec un vérificateur de requests==2.9.0liens

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

Résoudre tous les problèmes qui peuvent survenir. Les liens internes sont vérifiés sur Circle CI, cela ne devrait signaler que les liens externes défaillants.

Mettre à jour les versions prises en charge dans SECURITY.md #

Pour les versions mineures, mettez à jour le tableau SECURITY.mdpour spécifier que les 2 versions mineures les plus récentes de la série de versions majeures actuelle sont prises en charge.

Pour une version majeure, mettez à jour le tableau SECURITY.mdpour spécifier que la dernière version mineure de la série de versions majeures précédente est toujours prise en charge. L'abandon de la prise en charge de la dernière version d'une série de versions majeures sera géré au cas par cas.

Créer un commit de release et un tag #

Pour créer la balise, créez d'abord un commit vide avec un ensemble très succinct des notes de version dans le message de commit

git commit --allow-empty

puis créez une balise signée et annotée avec le même texte dans le corps du message

git tag -a -s v2.0.0

qui vous demandera votre mot de passe de clé GPG et une annotation. Pour les versions préliminaires, il est important de suivrePEP 440 afin que les artefacts de construction soient triés correctement dans PyPI.

Pour éviter les problèmes avec les constructeurs en aval qui téléchargent l'archive depuis GitHub, il est important d'éloigner toutes les branches du commit avec la balise [ 1 ] :

git commit --allow-empty

Enfin, poussez la balise vers GitHub :

git push DANGER main v2.0.0

Félicitations, le plus effrayant est fait !

S'il s'agit d'une version finale, créez également une branche 'doc' (cela n'est pas fait pour les pré-versions) :

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

et s'il s'agit d'une version majeure ou mineure, créez également une branche de correction de bogues (une micro version sera coupée de cette branche) :

git branch v2.0.x

Sur cette branche décommentez les globs de Update et validez les docs . Et alors

git push DANGER v2.0.x

Gestion des versions / DOI #

Via l' interface utilisateur GitHub , transformez la balise nouvellement poussée en version. S'il s'agit d'une pré-version, n'oubliez pas de la marquer comme telle.

Pour les versions finales, obtenez également le DOI de zenodo (qui en produira automatiquement un une fois la balise poussée). Ajoutez le post-fixe doi et la version au dictionnaire tools/cache_zenodo_svg.pyet exécutez le script.

Cela téléchargera le nouveau svg dans le _staticrépertoire de la documentation et le modifiera doc/citing.rst. Validez le nouveau svg, le changement vers tools/cache_zenodo_svg.py, et les changements vers doc/citing.rstla branche VER-doc et poussez vers 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

Construire des binaires #

Nous distribuons macOS, Windows et de nombreuses roues Linux ainsi qu'un tarball source via PyPI. La plupart des compilateurs devraient se déclencher automatiquement une fois la balise transmise à GitHub :

  • Les roues Windows, macOS et manylinux sont construites sur GitHub Actions. Les builds sont déclenchés par l'action GitHub définie dans .github/workflows/cibuildwheel.yml, et les roues seront disponibles en tant qu'artefacts du build.

  • Les roues Windows alternatives sont automatiquement construites par Christoph Gohlke et seront disponibles sur son site une fois construites.

  • Le bot automatique doit ouvrir une demande d'extraction dans la matière première conda-forge . Passez en revue et fusionnez (si vous en avez le pouvoir).

Avertissement

Étant donné que cela est automatisé, il est extrêmement important d'éloigner toutes les branches de la balise, comme indiqué dans Créer un commit et une balise de version .

S'il s'agit d'une version finale, les conditionneurs en aval suivants doivent être contactés :

  • DebianName

  • Feutre

  • Cambre

  • Gentoo

  • Macports

  • Brassage maison

  • Continuum

  • pensé

Cela peut être fait avant de collecter tous les fichiers binaires et de les télécharger sur pypi.

Faire la distribution et télécharger sur PyPI #

Une fois que vous avez collecté toutes les roues (attendez-vous à ce que cela prenne environ une journée), générez l'archive

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

et copiez toutes les roues dans le distrépertoire. Tout d'abord, vérifiez que les fichiers dist sont OK

twine check dist/*

puis utilisez twinepour télécharger tous les fichiers sur pypi

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

Félicitations, vous avez maintenant fait la deuxième partie la plus effrayante !

Construire et déployer la documentation #

Pour créer la documentation, vous devez avoir installé la version avec balises, mais créez la documentation à partir de la ver-docbranche. Un moyen simple d'organiser cela est:

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"

qui construira à la fois la version html et pdf de la documentation.

La documentation construite existe dans le référentiel matplotlib.github.com . Pousser les modifications vers main met automatiquement à jour le site Web.

La documentation est organisée par version. A la racine de l'arborescence se trouve toujours la documentation de la dernière version stable. En dessous, il y a des répertoires contenant la documentation des anciennes versions. La documentation pour main actuelle est construite sur Circle CI et poussée vers le référentiel devdocs . Ceux-ci sont disponibles sur matplotlib.org/devdocs .

En supposant que vous avez extrait ce référentiel dans le même répertoire que matplotlib

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

qui copiera les documents construits. S'il s'agit d'une version finale, liez le sous- stablerépertoire à la version la plus récente :

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

Vous devrez modifier manuellement versions.htmlpour afficher les 3 dernières versions balisées. Vous devrez également modifier sitemap.xmlpour inclure la nouvelle version publiée. Maintenant, validez et transférez tout sur GitHub

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

Félicitations, vous avez maintenant fait la troisième partie la plus effrayante !

Si vous y avez accès, effacez les caches Cloudflare.

Il faut généralement environ 5 à 10 minutes à GitHub pour traiter le push et mettre à jour la page Web en direct (n'oubliez pas de vider le cache de votre navigateur).

Annonce #

La dernière étape consiste à annoncer la sortie au monde. Une version courte des notes de version accompagnée des remerciements doit être envoyée à

Pour les versions finales, les annonces doivent également être envoyées aux listes de diffusion numpy/scipy/scikit-image.

De plus, des annonces doivent être faites sur les réseaux sociaux (twitter via le @matplotlibcompte, tout autre via des comptes personnels). NumFOCUS doit être contacté pour être inclus dans sa newsletter.

Forfaits Conda #

Le projet Matplotlib lui-même ne publie pas de packages conda. En particulier, le gestionnaire de version Matplotlib n'est pas responsable de l'empaquetage conda.

Pour plus d'informations sur l'empaquetage de Matplotlib pour conda-forge, voir https://github.com/conda-forge/matplotlib-feedstock .