Guía de lanzamiento #

Este documento solo es relevante para los administradores de versiones de Matplotlib.

Una guía para desarrolladores que están haciendo un lanzamiento de Matplotlib.

Nota

Esto supone que hay un control remoto de solo lectura para el repositorio canónico remotey un control remoto de lectura/escritura esDANGER

prueba #

Usamos GitHub Actions para la integración continua. Al prepararse para un lanzamiento, la confirmación etiquetada final debe probarse localmente antes de cargarse:

pytest -n 8 .

Además, se debe ejecutar e inspeccionar manualmente la siguiente prueba:

python tools/memleak.py agg 1000 agg.pdf

Además, se debe ejecutar e inspeccionar manualmente lo siguiente, pero actualmente no funciona:

pushd examples/tests/
python backend_driver_sgskip.py
popd

Estadísticas de GitHub #

Extraemos automáticamente el problema de GitHub, los PR y los autores de GitHub a través de la API. Copie el actual doc/users/github_stats.rsta doc/users/prev_whats_new/github_stats_X.Y.Z.rst, cambie el destino del enlace en la parte superior del archivo y elimine la sección "Estadísticas anteriores de GitHub" al final.

Por ejemplo, al actualizar de v3.2.0 a 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

Luego vuelva a generar las estadísticas actualizadas:

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

Revisar y confirmar cambios. Es posible que algunos títulos de problemas/PR no sean reST válidos (el problema más común es *que se interprete como marcado no cerrado).

Nota

Asegúrese de autenticarse con la API de GitHub. Si no lo hace, GitHub lo bloqueará por superar los límites de tasa de API. Puede autenticarse de una de dos maneras:

  • usando el keyringpaquete; y luego, cuando ejecute el script de estadísticas, se le solicitará el nombre de usuario y la contraseña, que se almacenarán en el conjunto de claves de su sistema, o,pip install keyring

  • usando un token de acceso personal; genere un nuevo token en esta página de GitHub con el repo:public_repo alcance y coloque el token en ~/.ghoauth.

Actualice y valide los documentos #

Fusionar *-docrama #

Combine la rama 'doc' más reciente (p. ej., v3.2.0-doc) en la rama que va a etiquetar y elimine la rama doc en GitHub.

Actualice las versiones admitidas en la política de seguridad #

Al realizar versiones principales o secundarias, actualice las versiones admitidas en la Política de seguridad en SECURITY.md. Por lo general, puede tratarse de una o dos versiones menores anteriores, pero depende de los administradores de versiones.

Actualizar notas de la versión #

Novedades #

Solo se necesita para lanzamientos mayores y menores. Los lanzamientos de corrección de errores no deberían tener nuevas funciones.

Combine el contenido de todos los archivos en doc/users/next_whats_new/ un solo archivo doc/users/prev_whats_new/whats_new_X.Y.0.rst y elimine los archivos individuales.

Cambios en la API #

Se necesita principalmente para lanzamientos mayores y menores. A veces podemos tener cambios en la API en las versiones de corrección de errores.

Combine el contenido de todos los archivos en doc/api/next_api_changes/ un solo archivo doc/api/prev_api_changes/api_changes_X.Y.Z.rst y elimine los archivos individuales.

Notas de la versión TOC #

Actualizar doc/users/release_notes.rst:

  • Para lanzamientos mayores y menores agregue una nueva sección

    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

  • Para lanzamientos de corrección de errores, agregue las estadísticas de GitHub y (si está presente) los cambios de API a la sección XY existente

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

Cambiar de versión de actualización #

Actualizar doc/_static/switcher.json_ Si es un lanzamiento menor X.Y.Z, cree una nueva entrada y cambie el nombre de estable . Si es un lanzamiento principal , cambie el nombre de y agregue una nueva versión para el estable anterior.version: X.Y.(Z-1)name: stable/X.Y.ZX.Y.0name: devel/X.(Y+1)name: stable/X.Y.0

Verifique que los documentos compilan #

Finalmente, asegúrese de que los documentos se construyan limpiamente.

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

Una vez creados los documentos, compruebe que todos los enlaces, internos y externos, siguen siendo válidos. Usamos linkcheckerpara esto, que aún no ha sido portado a Python3. Deberá crear un entorno de Python2 con un verificador de requests==2.9.0enlaces

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

Abordar cualquier problema que pueda surgir. Los enlaces internos se verifican en Circle CI, esto solo debería marcar los enlaces externos fallidos.

Actualice las versiones compatibles en SECURITY.md #

Para la versión secundaria, actualice la tabla SECURITY.mdpara especificar que se admiten las 2 versiones secundarias más recientes de la serie de versiones principales actual.

Para el lanzamiento de una versión principal, actualice la tabla SECURITY.mdpara especificar que la última versión secundaria de la serie de versiones principales anterior aún es compatible. La eliminación del soporte para la última versión de una serie de versiones principales se gestionará de forma ad hoc.

Crear compromiso de lanzamiento y etiquetar #

Para crear la etiqueta, primero cree una confirmación vacía con un conjunto muy conciso de las notas de la versión en el mensaje de confirmación.

git commit --allow-empty

y luego cree una etiqueta firmada y anotada con el mismo texto en el mensaje del cuerpo

git tag -a -s v2.0.0

que le pedirá la contraseña de su clave GPG y una anotación. Para prelanzamientos es importante seguirPEP 440 para que los artefactos de compilación se clasifiquen correctamente en PyPI.

Para evitar problemas con los constructores posteriores que descargan el tarball de GitHub, es importante alejar todas las ramas de la confirmación con la etiqueta [ 1 ] :

git commit --allow-empty

Finalmente, envíe la etiqueta a GitHub:

git push DANGER main v2.0.0

¡Felicitaciones, la parte más aterradora está hecha!

Si se trata de una versión final, cree también una rama 'doc' (esto no se hace para versiones preliminares):

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

y si se trata de una versión principal o secundaria, también cree una rama de corrección de errores (se eliminará una versión micro de esta rama):

git branch v2.0.x

En esta rama, elimine los comentarios de los globos de Actualizar y valide los documentos . Y entonces

git push DANGER v2.0.x

Gestión de versiones / DOI #

A través de la interfaz de usuario de GitHub , convierta la etiqueta recién enviada en un lanzamiento. Si se trata de un prelanzamiento, recuerde marcarlo como tal.

Para los lanzamientos finales, también obtenga el DOI de zenodo (que automáticamente producirá uno una vez que se presione la etiqueta). Agregue el arreglo posterior de doi y la versión al diccionario tools/cache_zenodo_svg.pyy ejecute el script.

Esto descargará el nuevo svg al _staticdirectorio en los documentos y lo editará doc/citing.rst. Confirme el nuevo svg, el cambio a tools/cache_zenodo_svg.pyy los cambios a doc/citing.rstla rama VER-doc y empuje a 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

Construyendo binarios #

Distribuimos macOS, Windows y muchas ruedas de Linux, así como un tarball fuente a través de PyPI. La mayoría de los constructores deberían activarse automáticamente una vez que la etiqueta se envía a GitHub:

  • Las ruedas de Windows, macOS y manylinux se basan en GitHub Actions. Las compilaciones se activan mediante la acción de GitHub definida en .github/workflows/cibuildwheel.ymly las ruedas estarán disponibles como artefactos de la compilación.

  • Christoph Gohlke crea ruedas de Windows alternativas automáticamente y estarán disponibles en su sitio una vez construidas.

  • El bot de marcación automática debería abrir una solicitud de extracción en la materia prima de conda-forge . Revisa y fusiona (si tienes el poder de hacerlo).

Advertencia

Debido a que esto está automatizado, es extremadamente importante eliminar todas las ramas de la etiqueta, como se explica en Crear confirmación y etiqueta de lanzamiento .

Si se trata de una versión final, se debe contactar a los siguientes empaquetadores intermedios:

  • Debian

  • Fedora

  • Arco

  • Gentoo

  • Macports

  • Cerveza casera

  • continuo

  • pensado

Esto se puede hacer antes de recopilar todos los archivos binarios y cargarlos en pypi.

Hacer distribución y subir a PyPI #

Una vez que haya recolectado todas las ruedas (espere que esto tome alrededor de un día), genere el tarball

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

y copie todas las ruedas en el distdirectorio. Primero, verifique que los archivos dist estén bien

twine check dist/*

y luego use twinepara cargar todos los archivos a pypi

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

¡Felicitaciones, ahora has hecho la segunda parte más aterradora!

Documentación de compilación e implementación #

Para crear la documentación, debe tener instalada la versión etiquetada, pero cree los documentos desde la ver-docrama. Una manera fácil de arreglar esto es:

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"

que construirá la versión html y pdf de la documentación.

La documentación construida existe en el repositorio matplotlib.github.com . Al presionar los cambios en la página principal, se actualiza automáticamente el sitio web.

La documentación está organizada por versión. En la raíz del árbol siempre se encuentra la documentación de la última versión estable. Debajo de eso, hay directorios que contienen la documentación para versiones anteriores. La documentación para main actual se basa en Circle CI y se envía al repositorio devdocs . Estos están disponibles en matplotlib.org/devdocs .

Suponiendo que tiene este repositorio desprotegido en el mismo directorio 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

que copiará los documentos creados. Si se trata de una versión final, vincule el stablesubdirectorio a la versión más reciente:

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

Deberá editar manualmente versions.htmlpara mostrar las últimas 3 versiones etiquetadas. También deberá editar sitemap.xmlpara incluir la versión recién lanzada. Ahora confirme y envíe todo a GitHub

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

¡Felicitaciones, ahora has hecho la tercera parte más aterradora!

Si tiene acceso, borre los cachés de Cloudflare.

Por lo general, GitHub tarda entre 5 y 10 minutos en procesar el envío y actualizar la página web en vivo (recuerde borrar la memoria caché de su navegador).

anunciando #

El paso final es anunciar el lanzamiento al mundo. Se debe enviar una versión corta de las notas de la versión junto con los agradecimientos a

Para los lanzamientos finales, los anuncios también deben enviarse a las listas de correo numpy/scipy/scikit-image.

Además, se deberán realizar anuncios en redes sociales (twitter a través de la @matplotlibcuenta, cualquier otro a través de cuentas personales). Se debe contactar a NumFOCUS para incluirlo en su boletín informativo.

Paquetes Conda #

El proyecto Matplotlib en sí no libera paquetes conda. En particular, el administrador de versiones de Matplotlib no es responsable del empaquetado de conda.

Para obtener información sobre el paquete de Matplotlib para conda-forge, consulte https://github.com/conda-forge/matplotlib-feedstock .