Directrices de solicitud de extracción #

Las solicitudes de extracción (PR) son el mecanismo para contribuir al código y la documentación de Matplotlibs.

Resumen para autores de solicitudes de incorporación de cambios #

Nota

  • Valoramos las contribuciones de personas con todos los niveles de experiencia. En particular, si esta es su primera RP, no todo tiene que ser perfecto. Lo guiaremos a través del proceso de relaciones públicas.

  • Sin embargo, intente seguir las pautas a continuación lo mejor que pueda para ayudar a que el proceso de relaciones públicas sea rápido y sin problemas.

  • Sea paciente con los revisores. Hacemos todo lo posible para responder rápidamente, pero tenemos un ancho de banda limitado. Si no hay comentarios dentro de un par de días, envíenos un mensaje publicando un comentario en su PR.

Al hacer un PR, preste atención a:

  • Apunta a la rama principal .

  • Cumplir con las pautas de codificación .

  • Actualizar la documentación si es necesario.

  • Apunta a hacer que las relaciones públicas estén lo más "listas para usar" que puedas. Esto ayuda a acelerar el proceso de revisión.

  • Está bien abrir PR incompletos o en progreso si necesita ayuda o comentarios de los desarrolladores. Puede marcarlos como borradores de solicitudes de extracción en GitHub.

  • Al actualizar su PR, en lugar de agregar nuevas confirmaciones para arreglar algo, considere modificar su(s) confirmación(es) inicial(es) para mantener limpio el historial. Puedes lograr esto usando

    git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease

Consulte también Contribuir para saber cómo hacer un PR.

Resumen para revisores de solicitudes de incorporación de cambios #

Nota

  • Si tiene derechos de confirmación, se le confía su uso. ¡Ayúdenos a revisar y fusionar las relaciones públicas!

  • Sea paciente y amable con los colaboradores.

Temas de contenido:

  • ¿Es razonable la función/corrección de errores?

  • ¿Se ajusta el PR a las pautas de codificación ?

  • ¿Está actualizada la documentación (docstrings, ejemplos, novedades, cambios en la API)?

Temas organizativos:

Directrices detalladas #

Documentación #

  • Cada nueva característica debe ser documentada. Si es un módulo nuevo, no olvide agregar un nuevo primer archivo a los documentos de la API.

  • Cada función de trazado de alto nivel debe tener un pequeño ejemplo en la Examplessección de la cadena de documentación. Esto debe ser lo más simple posible para demostrar el método. Los ejemplos más complejos deben ir a un archivo de ejemplo dedicado en el examplesdirectorio, que se representará en la galería de ejemplos en la documentación.

  • Cree los documentos y asegúrese de que se aborden todas las advertencias de formato.

  • Consulte Escritura de documentación para conocer nuestra guía de estilo de documentación.

  • Si su cambio es una característica nueva importante, agregue una entrada a doc/users/whats_new.rst.

  • Si cambia la API de forma incompatible con versiones anteriores, documéntelo agregando un archivo en el subdirectorio correspondiente de doc/api/next_api_changes/, probablemente en el behavior/ subdirectorio.

Etiquetas #

  • Si tiene los derechos para establecer etiquetas, etiquete el PR con etiquetas descriptivas. Consulte la lista de etiquetas .

  • Si el RP realiza cambios en la acción de creación de ruedas, agregue la etiqueta "Ejecutar rueda de construcción" para habilitar la prueba de ruedas.

Hitos #

  • Establezca el hito de acuerdo con estas reglas:

    • Las nuevas funciones y los cambios en la API están marcados para la próxima versión menor v3.X.0.

    • Las correcciones de errores y los cambios en la cadena de documentación se marcan para el próximo lanzamiento del parchev3.X.Y

    • Los cambios en la documentación (todos los archivos .rst y ejemplos) se marcan con hitos v3.X-doc

    Si se aplican varias reglas, elija la primera coincidencia de la lista anterior.

    Establecer un hito no implica ni garantiza que un PR se fusionará para esa versión, pero si se fusionara, en qué versión estaría.

    Todos estos PR deben apuntar a la sucursal principal. La etiqueta de hito desencadena una retroportación automática para los hitos que tienen una rama correspondiente.

Fusionando #

  • El primer revisor puede fusionar la documentación y los ejemplos. Utilice el umbral "¿es esto mejor de lo que era?" como criterio de revisión.

  • Para cambios de código (cualquier cosa en srco lib), al menos dos desarrolladores principales (aquellos con derechos de compromiso) deben revisar todas las solicitudes de incorporación de cambios. Si es el primero en revisar un PR y aprobar los cambios, use la herramienta "aprobar revisión" de GitHub para marcarlo como tal. Si es un revisor posterior, apruebe la revisión y, si cree que no se necesita más revisión, fusione el RP.

    Asegúrese de que todos los cambios de la API estén documentados en un archivo en uno de los subdirectorios de doc/api/next_api_changesy que las nuevas características significativas tengan una entrada en doc/user/whats_new.

    • Si un RP ya tiene una revisión positiva, un desarrollador principal (p. ej., el primer revisor, pero no necesariamente) puede promover la fusión de ese RP. Para hacerlo, deben hacer ping a todos los desarrolladores principales tanto en GitHub como en la lista de correo de desarrolladores, y etiquetar el PR con el mensaje "¿Combinar con revisión única?" etiqueta. Otros desarrolladores principales pueden revisar la RP y fusionarla o rechazarla, o simplemente solicitar que obtenga una segunda revisión antes de fusionarse. Si nadie solicita una segunda revisión de este tipo dentro de una semana, el RP puede fusionarse sobre la base de esa única revisión.

      Un desarrollador central solo debe defender un RP a la vez y debemos tratar de mantener un flujo razonable de RP defendidos.

  • No se auto fusione, excepto en parches "pequeños" para corregir el CI o cuando otro revisor lo permita explícitamente (p. ej., "Aprobar módulo CI aprobado, puede auto fusionarse cuando esté verde").

Pruebas automatizadas #

Cada vez que se crea o actualiza una solicitud de extracción, se ejecutarán varias herramientas de prueba automatizadas en todas las plataformas y versiones compatibles de Python.

  • Asegúrese de que las canalizaciones de Linting, GitHub Actions, AppVeyor, CircleCI y Azure estén pasando antes de fusionarse (todas las comprobaciones se enumeran en la parte inferior de la página de GitHub de su solicitud de extracción). Aquí hay algunos consejos para encontrar la causa de la falla de la prueba:

    • Si Linting falla, tiene un problema de estilo de código, que aparecerá como anotaciones en la diferencia de la solicitud de extracción.

    • Si falla una ejecución de GitHub Actions o AppVeyor, busque en el registro FAILURES. La sección siguiente contendrá información sobre las pruebas fallidas.

    • Si CircleCI falla, es probable que tenga algún problema de estilo reStructuredText en los documentos. Busque el registro de CircleCI para WARNING.

    • Si las canalizaciones de Azure fallan con un error de comparación de imágenes, puede encontrar las imágenes como artefactos del trabajo de Azure:

      • Haga clic en Detalles en el cheque en la página de relaciones públicas de GitHub.

      • Haga clic en Ver más detalles en Azure Pipelines para ir a Azure.

      • En la página de descripción general, los artefactos se enumeran en la sección Relacionados .

  • Codecov y LGTM son actualmente solo para información. Su fracaso no es necesariamente un bloqueador.

  • tox no se utiliza en las pruebas automatizadas. Es compatible para probar localmente.

  • Si sabe que no es necesario probar sus cambios (¡esto es muy raro!), todos los CI se pueden omitir para una confirmación dada al incluir o en el mensaje de confirmación. Si sabe que solo es necesario ejecutar un subconjunto de elementos de configuración (p. ej., si está cambiando algún bloque de texto reestructurado sin formato y desea que solo se ejecute CircleCI para representar el resultado), los elementos de configuración individuales también se pueden omitir en confirmaciones individuales utilizando lo siguiente subcadenas en mensajes de confirmación:[ci skip][skip ci]

    • Acciones de GitHub:[skip actions]

    • AppVeyor: (debe estar en la primera línea de la confirmación)[skip appveyor]

    • Canalizaciones de Azure:[skip azp]

    • Círculo CI:[skip circle]

Número de confirmaciones y aplastamiento #

  • El aplastamiento es caso por caso. El equilibrio está entre la carga para el contribuyente, mantener un historial relativamente limpio y mantener un historial utilizable para la bisección. La única vez que somos realmente estrictos al respecto es eliminar archivos binarios (por ejemplo, regeneraciones múltiples de imágenes de prueba) y eliminar fusiones ascendentes.

  • No dejes que lo perfecto sea enemigo de lo bueno, especialmente en documentación o relaciones públicas de ejemplo. Si te encuentras haciendo muchas sugerencias pequeñas, abre un PR contra la rama original, envía cambios a la rama colaboradora o fusiona el PR y luego abre un nuevo PR contra upstream.

  • Si empujas a una sucursal colaboradora, deja un comentario que explique lo que hiciste, por ejemplo, "Me tomé la libertad de empujar una pequeña limpieza de relaciones públicas a tu sucursal, gracias por tu trabajo". Si va a realizar cambios sustanciales en el código o la intención del RP, consulte primero con el colaborador.

Sucursales y backports #

Sucursales actuales #

Las sucursales activas actuales son

principal

La versión de desarrollo actual. Futuras versiones menores ( v3.N.0 ) se derivarán de esto.

v3.Nx

Rama de mantenimiento para Matplotlib 3.N. Los futuros lanzamientos de parches se ramificarán a partir de esto.

v3.NM-doc

Documentación para la versión actual. En un lanzamiento de parche, esto será reemplazado por una rama con el nombre adecuado para el nuevo lanzamiento.

Selección de rama para solicitudes de extracción #

En general, todas las solicitudes de extracción deben dirigirse a la rama principal.

Otros ramales se alimentan de forma automática o manual . Rara vez es necesario dirigirse directamente a otras sucursales para trabajos de mantenimiento especiales.

Estrategia de backport #

Siempre haremos un backport a la rama de lanzamiento del parche ( v3.Nx ):

  • correcciones de errores críticos (segfault, falla en la importación, cosas que el usuario no puede solucionar)

  • arreglos para regresiones contra las últimas dos versiones.

Todo lo demás (regresiones contra versiones anteriores, errores/inconsistencias de API que el usuario puede solucionar en su código) se analizan caso por caso, debe ser de bajo riesgo y necesita a alguien que lo defienda y lo guíe a través del backport.

Los únicos cambios que se transferirán a la rama de documentación ( v3.NM-doc ) son los cambios a doc, exampleso tutorials. Cualquier cambio en libo que srcincluya cambios solo en la cadena de documentación no debe transferirse a esta rama.

Backports automatizados #

Usamos el bot meeseeksdev para retrotraer automáticamente las fusiones a la base de sucursal de mantenimiento correcta en el hito. Para que funcione correctamente, el hito debe establecerse antes de la fusión. Si tiene derechos de compromiso, el bot también se puede activar manualmente después de una fusión dejando un mensaje en el PR. Si hay conflictos, meeseekdevs le informará que el backport debe realizarse manualmente.@meeseeksdev backport to BRANCH

La rama de destino se configura poniendo la descripción del hito en su propia línea.on-merge: backport to TARGETBRANCH

Si el bot no funciona como se esperaba, informe los problemas a Meeseeksdev .

Adaptaciones manuales #

Al realizar backports, copie el formulario utilizado por meeseekdev, . Si necesita resolver conflictos manualmente, anótelos y cómo los resolvió en el mensaje de confirmación.Backport PR #XXXX: TITLE OF PR

Hacemos un backport de main a v2.2.x asumiendo:

  • matplotlibes una rama remota de solo lectura del repositorio matplotlib/matplotlib

El TARGET_SHAes el hash de la confirmación de fusión que le gustaría respaldar. Esto se puede leer en la página de relaciones públicas de GitHub (en la interfaz de usuario con la notificación de fusión) o a través de las herramientas de la CLI de git.

Suponiendo que ya tiene una sucursal local v2.2.x(si no, entonces ), y que su control remoto se llama :git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

Los archivos con conflictos se pueden enumerar por , y deberán corregirse a mano (buscar en ). Una vez que se resuelva el conflicto, deberá volver a agregar los archivos a la rama y luego continuar con la selección:git status>>>>>

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

Use su discreción para empujar directamente a upstream o para abrir un PR; ¡ asegúrese de empujar o PR contra la v2.2.xrama aguas arriba, no main!