Información sobre el mantenedor/desarrollador del núcleo

Lanzamiento de versiones

Esta sección trata de preparar una versión mayor, incrementar la versión menor, o una versión de corrección de errores incrementando la versión del parche. Nuestra convención es que lanzamos uno o más candidatos a la versión (0.RRrcN) antes de lanzar las distribuciones finales. Seguimos el PEP101 para indicar los candidatos de lanzamiento, mensajes y versiones menores.

Antes de una versión

  1. Actualizar tabla de autores:

    cd build_tools; make authors; cd ..

    y hacer commit. Esto sólo es necesario si los autores han cambiado desde la última versión. Este paso a veces se hace independientemente de la versión. Esto actualiza la lista de mantenedores y no es la lista de colaboradores de la versión.

  2. Confirma que los bloqueos marcados para el hito se han resuelto y que otros asuntos marcados para el hito pueden posponerse.

  3. Asegura que el registro de cambios y los commits se corresponden (¡dentro de lo razonable!), y que el registro de cambios está razonablemente bien curado. Algunas herramientas para estas tareas son:

    • maint_tools/sort_whats_new.py puede poner las entradas nuevas en secciones. No es perfecto, y requiere una comprobación manual de los cambios. Si la lista de novedades está bien curada, puede no ser necesario.

    • El script maint_tools/whats_missing.sh puede ser usado para identificar solicitudes de pull que fueron fusionadas, pero probablemente faltan de What’s New.

  4. Asegúrate de que las obsolescencias, FIXME y TODOs etiquetadas para la versión han sido atendidos.

Permisos

El gestor de lanzamiento requiere un conjunto de permisos además de los permisos habituales otorgados a los mantenedores, los cuales incluyen:

  • Rol de maintainer en los proyectos scikit-learn en pypi.org y test.pypi.org, por separado.

  • hazte miembro del equipo scikit-learn en conda-forge editando el archivo recipe/meta.yaml en https://github.com/conda-forge/scikit-learn-feedstock

Preparando un PR de lanzamiento

Lanzamiento de la versión principal

Antes de bifurcarse, por favor, no olvides preparar una página de aspectos destacados de la versión como un ejemplo ejecutable y comprueba que su renderización HTML parezca correcta. Estos aspectos destacados de la versión deben ser enlazados desde el archivo doc/whats_new/v0.99.rst para la nueva versión de scikit-learn.

Publicar la primera RC de, por ejemplo, la versión 0.99.0 implica crear la rama de lanzamiento 0.99.X directamente en el repositorio principal, donde X es realmente la letra X, no un marcador de posición. El desarrollo de las versiones mayores y menores de 0.99 debería también ocurrir bajo 0.99.X. Cada versión (rc, mayor o menor) es una etiqueta bajo esa rama.

Esto se hace sólo una vez, ya que las versiones principales y menores ocurren en la misma rama:

# Assuming upstream is an alias for the main scikit-learn repo:
git fetch upstream main
git checkout upstream/main
git checkout -b 0.99.X
git push --set-upstream upstream 0.99.X

De nuevo, X es literal aquí, y 99 es reemplazado por el número de lanzamiento. Las ramas se llaman 0.19.X, 0.20.X, etc.

En cuanto a la inclusión de cambios, la primera RC cuenta idealmente como una congelación de características. Cada versión candidata y la versión final posterior incluirán únicamente cambios menores en la documentación y correcciones de errores. Cualquier mejora o característica importante debe ser excluida.

A continuación, puedes preparar una rama local para el lanzamiento en sí, por ejemplo: release-0.99.0rc1, hacer push a tu fork de github y abrir un puul request a la rama scikit-learn/0.99.X. Copia las plantillas Lista de verificación de lanzamiento en la descripción del Pull Request para seguir el progreso.

Esta PR se utilizará para hacer push a commits relacionados con la versión, como se explica en Haciendo un lanzamiento.

También puedes crear un segundo PR desde main y apuntar a main para incrementar la variable __versión__ en sklearn/__init__.py para incrementar la versión dev. Esto significa que mientras estemos en el periodo de lanzamiento de la versión candidata, la última estable está dos versiones por detrás de la rama principal, en lugar de una. En este PR dirigido a la rama principal, también deberías incluir un nuevo archivo para la versión correspondiente en la carpeta doc/whats_new/ para que los PRs dirigidos a la siguiente versión puedan contribuir con sus entradas de registro de cambios a este archivo en paralelo al proceso de lanzamiento.

Lanzamiento de una versión menor

Las versiones menores deben incluir únicamente correcciones de errores y algunos cambios relevantes en la documentación. Cualquier PR que resulte en un cambio de comportamiento que no sea una corrección de errores debe ser excluido.

Primero, crea una rama, en tu propio fork (para lanzar por ejemplo, 0.99.3):

# assuming main and upstream/main are the same
git checkout -b release-0.99.3 main

A continuación, crea un pull request en la rama scikit-learn/0.99.X (¡no en main!) con todos los cambios deseados:

git rebase -i upstream/0.99.2

Copia las plantillas Lista de verificación de lanzamiento en la descripción de la Pull Request para seguir el progreso.

No olvides añadir un commit actualizando sklearn.__version__.

Es bueno tener una copia del registro git rebase -i en el PR para ayudar a otros a entender lo que está incluido.

Haciendo un lanzamiento

  1. Asegúrate de que has comprobado la rama de la versión PR como se explica en Preparando un PR de lanzamiento más arriba.

  2. Actualizar la documentación. Ten en cuenta que esto es para la versión final, no necesariamente para las versiones RC. Estos cambios deben ser realizados en la rama principal y llevados a la rama de lanzamiento, sólo antes de la versión final.

    • Edita el archivo doc/whats_new/v0.99.rst para añadir el título de la liberación y la lista de colaboradores. Puedes recuperar la lista de nombres de colaboradores con:

      $ git shortlog -s 0.98.33.. | cut -f2- | sort --ignore-case | tr '\n' ';' | sed 's/;/, /g;s/, $//' | fold -s

      • Para versiones principales, enlaza el ejemplo de la versión destacada del archivo doc/whats_new/v0.99.rst.

    • Actualiza la fecha de lanzamiento en whats_new.rst

    • Edita el doc/templates/index.html para cambiar la entrada “Noticias” de la página principal (con el mes de lanzamiento también).

  3. En la rama de lanzamiento, actualiza el número de versión en sklearn/__init__.py, el __version__.

    Para versiones principales, por favor añade un 0 al final: 0.99.0 en lugar de 0.99.

    Para la primera versión candidata, utiliza el sufijo rc1 en el número esperado de la versión final: 0.99.0rc1.

  4. Activa el compilador de wheel con el marcador de commit [cd build] usando el comando:

    git commit --allow-empty -m "Trigger wheel builder workflow: [cd build]"

    El flujo de trabajo de compilación de wheels es administrado por GitHub Actions y los resultados se revisan en: https://github.com/scikit-learn/scikit-learn/actions?query=workflow%3A%22wheel+builder%22

Nota

Antes de compilar los wheels, asegúrate de que el archivo``pyproject.toml`` está actualizado y utiliza la versión más antigua de numpy para cada versión de Python para evitar IBA problemas de incompatibilidad. Además, hay que incluir una nueva línea en el archivo pyproject.toml para cada nueva versión soportada de Python.

Nota

El acrónimo CD en [cd build] significa Entrega Continua y se refiere a la automatización utilizada para generar los artefactos de liberación (binarios y paquetes fuentes). Esto puede ser visto como una extensión de CI que significa Integración continua. El flujo de trabajo de GitHub Actions también se utiliza para crear automáticamente compilaciones nocturnas y publicar paquetes para la rama de desarrollo de scikit-learn. Ver Instalación de compilaciones nocturnas.

  1. Una vez que todos los trabajos de CD se hayan completado con éxito en el PR, fusiónalo, de nuevo con el marcador [cd build] en el mensaje de confirmación. Esta vez los resultados se subirán a la zona de preparación.

    A continuación, deberías poder subir los artefactos generados (archivos .tar.gz y .whl) a https://test.pypi.org utilizando el formulario «Ejecutar flujo de trabajo» para el siguiente flujo de trabajo de GitHub Actions:

    https://github.com/scikit-learn/scikit-learn/actions?query=workflow%3A%22Publish+to+Pypi%22

  2. Si esto salió bien, puede continuar con el etiquetado. Procede con precaución. Idealmente, las etiquetas deben crearse cuando esté casi seguro de que la versión está lista, ya que añadir una etiqueta al repositorio principal puede desencadenar ciertos procesos automatizados.

    Crea la etiqueta y haz push (si es un RC, puede ser 0.xx.0rc1 por ejemplo):

    git tag -a 0.99.0  # in the 0.99.X branch
git push git@github.com:scikit-learn/scikit-learn.git 0.99.0

  3. Activa de nuevo el flujo de trabajo de GitHub Actions, pero esta vez para subir los artefactos al verdadero https://pypi.org (reemplazar «testpypi» por «pypi» en el formulario «Ejecutar flujo de trabajo»).

  4. Alternativamente, es posible recoger localmente los paquetes binarios generados de wheel y el tarball fuente y subirlos todos a PyPI ejecutando los siguientes comandos en la carpeta de la fuente de scikit-learn (comprobada en la etiqueta de lanzamiento):

    rm -r dist
pip install -U wheelhouse_uploader twine
python setup.py fetch_artifacts

    Este comando descargará todos los paquetes binarios acumulados en el área de staging en el servicio de alojamiento de anaconda.org <https://anaconda.org/scikit-learn-wheels-staging/scikit-learn/files>`_ y los pondrá en su carpeta local ./dist.

    Comprueba el contenido de la carpeta ./dist: debe contener todos los wheel junto con el tarball fuente («scikit-learn-RRR.tar.gz»).

    Asegúrate de que no tienes versiones del desarrollador o versiones antiguas del paquete scikit-learn en esa carpeta.

    Antes de subir a pypi, puedes probar la subida a test.pypi.org:

    twine upload --verbose --repository-url https://test.pypi.org/legacy/ dist/*

    Subir todo a la vez a https://pypi.org:

    twine upload dist/*

  5. Para la versión principal/menor (no versiones de corrección de errores), actualiza el symlink para stable y la variable latestStable en https://github.com/scikit-learn/scikit-learn.github.io:

    cd /tmp
git clone --depth 1 --no-checkout git@github.com:scikit-learn/scikit-learn.github.io.git
cd scikit-learn.github.io
echo stable > .git/info/sparse-checkout
git checkout master
rm stable
ln -s 0.999 stable
sed -i "s/latestStable = '.*/latestStable = '0.999';/" versionwarning.js
git add stable/ versionwarning.js
git commit -m "Update stable to point to 0.999"
git push origin master

Lista de verificación de lanzamiento

La siguiente lista de verificación de GitHub puede ser útil en una versión PR:

* [ ] update news and what's new date in release branch
* [ ] update news and what's new date and sklearn dev0 version in main branch
* [ ] check that the for the release wheels can be built successfully
* [ ] merge the PR with `[cd build]` commit message to upload wheels to the staging repo
* [ ] upload the wheels and source tarball to https://test.pypi.org
* [ ] create tag on the main github repo
* [ ] upload the wheels and source tarball to PyPI
* [ ] https://github.com/scikit-learn/scikit-learn/releases draft
* [ ] confirm bot detected at
  https://github.com/conda-forge/scikit-learn-feedstock and wait for merge
* [ ] https://github.com/scikit-learn/scikit-learn/releases publish
* [ ] fix the binder release version in ``.binder/requirement.txt`` (see
  #15847)
* [ ] announce on mailing list and on twitter

Fusión de Pull Requests

Los commits individuales se aplastan cuando se fusiona un Pull Request (PR) en Github. Antes de la fusión,

  • el título del commit resultante puede ser editado si es necesario. Ten en cuenta que esto cambiará el nombre del título del PR por defecto.

  • la descripción detallada, que contiene los títulos de todos los commits, puede ser editada o eliminada.

  • para los PRs con múltiples colaboradores de código se debe tener cuidado de mantener las etiquetas Co-autor por: nombre <name@example.com> en la descripción detallada. Esto marcará que el PR tiene múltiples coautores. Si las contribuciones de código son lo suficientemente significativas como para merecer la coautoría se deja a la discreción del mantenedor, al igual que para la entrada «what’s new».

El sitio web scikit-learn.org

El sitio web de scikit-learn (http://scikit-learn.org) está alojado en GitHub, pero rara vez debe ser actualizado manualmente empujando al repositorio https://github.com/scikit-learn/scikit-learn.github.io. La mayoría de las actualizaciones se pueden hacer subiendo a master (para /dev) o una rama de lanzamiento como 0.99.X, desde la cual Circle CI compila y sube la documentación automáticamente.

Trabajos de Travis Cron

De https://docs.travis-ci.com/user/cron-jobs: Los trabajos cron de Travis CI funcionan de forma similar a la utilidad cron, ejecutan compilaciones a intervalos regulares programados independientemente de si se ha enviado alguna confirmación al repositorio. Los trabajos cron siempre obtienen la confirmación más reciente en una rama particular y construyen el proyecto en ese estado. Las tareas Cron pueden ejecutarse diariamente, semanalmente o mensualmente, lo que en la práctica significa hasta una hora después del intervalo de tiempo seleccionado, y no se puede establecer que se ejecuten a una hora específica.

Para scikit-learn, los trabajos Cron se utilizan para las compilaciones que no queremos ejecutar en cada PR. Por ejemplo, la compilación con las versiones dev de numpy y scipy se ejecuta como un trabajo Cron. La mayoría de las veces, cuando esta compilación de numpy-dev falla, está relacionada con un cambio en numpy y no en scikit-learn, por lo que no tendría sentido culpar al autor del PR por la falla de Travis.

La definición de lo que se ejecuta en el trabajo Cron se hace en el archivo de configuración .travis.yml, exactamente de la misma manera que los otros trabajos de Travis. Usamos un filtro if: type = cron para que la compilación se ejecute sólo en trabajos Cron.

La rama dirigida por el trabajo de Cron y la frecuencia del trabajo de Cron se establece a través de la interfaz web en https://www.travis-ci.org/scikit-learn/scikit-learn/setting.

Características experimentales

El módulo sklearn.experimental fue introducido en 0.21 y contiene características / estimadores experimentales que están sujetos a cambios sin ciclo de obsolescencia.

Para crear un módulo experimental, solo puedes copiar y modificar el contenido de enable_Chan_gradient_boosting.py, o enable_iterative_imputer.py.

Ten en cuenta que la ruta de importación pública debe ser un subpaquete público (como sklearn/ensemble o sklearn/impute), no sólo un módulo .py. Además, las características experimentales (privadas) que se importan deben estar en un submódulo/subpaquete del subpaquete público, por ejemplo, sklearn/ensemble/_hist_gradient_boosting/ o sklearn/impute/_iterative.py. Esto es necesario para que los pickles sigan funcionando en el futuro cuando las características ya no sean experimentales.

Para evitar los errores del verificador de tipos (por ejemplo, mypy) se debe hacer una importación directa de los estimadores experimentales en el módulo padre, protegida por la comprobación if typing.TYPE_CHECKING. Ver sklearn/ensemble/__init__.py, o sklearn/impute/__init__.py para un ejemplo.

Por favor, escribe también pruebas básicas siguiendo las de test_enable_hist_gradient_boosting.py.

Asegúrate de que cada código de usuario que escriba menciones explícitamente que la característica es experimental, y agrega un comentario # noqa para evitar advertencias relacionadas con pep8:

# To use this experimental feature, we need to explicitly ask for it:
from sklearn.experimental import enable_hist_gradient_boosting  # noqa
from sklearn.ensemble import HistGradientBoostingRegressor

Para que los documentos se muestren correctamente, por favor importa también enable_my_experimental_feature en doc/conf.py, de lo contrario sphinx no podrá importar los módulos correspondientes. Ten en cuenta que el uso de from sklearn.experimental import * no funciona.

Ten en cuenta que algunas clases / funciones experimentales no están incluidas en el módulo sklearn.experimental: sklearn.datasets.fetch_openml.