Enviar una solicitud de extracción¶

Ahora que has confirmado todos tus cambios, estás listo para enviar una solicitud de extracción. Para asegurarte que el proceso de revisión se realiza sin problemas, debes seguir una serie de pasos.

Trabajar con pre-confirmación¶

Al confirmar cualquier cambio, se ejecutará automáticamente la precompromiso. Si se encuentra alguna incidencia con la confirmación, ésta fallará. Siempre que sea posible, pre-commit realizará los cambios necesarios para corregir los problemas encontrados. En el siguiente ejemplo, la comprobación ruff ha encontrado una incidencia de formato de código:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

En este caso, ruff solucionó el problema automáticamente; por lo que puede volver a añadir los archivos que se modificaron como resultado de las comprobaciones previas a la confirmación y volver a confirmar el cambio. Sin embargo, algunas comprobaciones requerirán que realices modificaciones manuales. Una vez que haya hecho esos cambios, vuelva a añadir cualquier archivo modificado y vuelva a confirmar.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Una vez que todo haya pasado, verás un mensaje indicando que la confirmación ha sido finalizada, y tu git log mostrará tu confirmación como la adición más reciente. Ya estás listo para subirlo a GitHub.

Sube tus cambios a GitHub y crea tu solicitud de extracción¶

La primera vez que hagas una extracción (push) a GitHub, se te proporcionará una URL que te llevará directamente a la página de GitHub para crear una solicitud de extracción nueva. Sigue la URL y crea tu «pull request».

A continuación se muestra un ejemplo de lo que se puede esperar de push, con la URL resaltada.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Si ya has enviado la rama actual a GitHub previamente subida, no volverás a recibir la URL. Sin embargo, hay otras formas de obtener a la URL de creación del RP:

Navegue hasta el repositorio upstream, pulse en "Pull Requests" seguido de "New pull request", y elija el desde el que desea enviar su pull request.
Si has extraído recientemente, navega al repositorio en desarrollo, localiza la pancarta por encima del listado de archivos que indican que el repositorio ha «tenido recientes extracciones», y pulsa el botón «Comparar y solicitar extracción».
Utiliza el comando gh pr create de la CLI de GitHub, y rellena las solicitudes.
Utiliza la instrucción de CLI GitHub gh pr create --web para abrir un navegador web en la página de creación del RP.

Cualquiera de estas opciones le habilitará para crear su pull request nuevo.

La CLI de GitHub: gh

GitHub proporciona la CLI de GitHub, la cual te da acceso a muchas de las prestaciones de GitHub desde tu terminal, a través de la instrucción gh. La documentación de CLI GitHub cubre todas las prestaciones.

Contenido de solicitud de extracción¶

El título de una solicitud de extracción debe ser informativo, claro y conciso. Intente que sea corto si es posible, pero se aceptan títulos más largos si es necesario. Un buen título de RP debe dar a una persona sin ningún contexto una idea razonablemente sólida de qué defecto o prestación se implementa en tu RP.

La descripción del RP debe reflejar claramente los cambios en el RP. Una persona sin ningún contexto debería ser capaz de leer su descripción, y obtener una comprensión relativamente completa de por qué se está realizando el cambio. Evite chistes, modismos, coloquialismos y formatos innecesarios, como el uso de mayúsculas o puntuación excesiva; se pretende que sea una explicación directa de lo que está sucediendo en su RP, y evitar esas cosas hace que la descripción sea más accesible para los demás.

Si hay algún caso de reproducción, o algún régimen de pruebas que haya utilizado que no forme ya parte de los cambios presentes en el RP, debe explicarse e incluirse en el RP. La explicación incluiría cómo ejecutarlos y qué hacer para reproducir el resultado deseado.

Si su pull request va a resolver la incidencia #1234, debe incluir el texto Fixes #1234 en la descripción de su pull request. Esto hará que la incidencia se cierre automáticamente cuando se fusione la pull request. Puede hacer referencia a otras discusiones, incidencias o pull requests utilizando la misma sintaxis #1234. Puede hacer referencia a una incidencia en un repositorio diferente anteponiendo el número; por ejemplo python/cpython#1234 haría referencia a la incidencia 1234 en el repositorio CPython.

Integración continua¶

La integración continua, o IC, es el proceso de ejecutar comprobaciones automatizadas en tu solicitud de extracción. Esto puede incluir comprobaciones sencillas, como asegurarse que el código está formateado correctamente; pero también incluye la ejecución del conjunto de pruebas y la creación de documentación.

Hay un gran número de cambios que pueden dar lugar a fallos de CI. En términos generales, no revisaremos un PR que no esté pasando CI. Si creas un pull request y CI falla, no comenzaremos su revisión hasta que esté pasando. Si sus cambios resultan en un fallo, es su responsabilidad investigar la razón y resolver la incidencia.

Cuando IC falla, los enlaces de fallo aparecerán en la parte inferior de la página RP, bajo el título «Algunas comprobaciones no se lograron». Verá una lista de comprobaciones incorrectas, que aparecerá en la parte superior de la lista de todas las comprobaciones si también hay comprobaciones correctas. Si pulsa sobre el enlace del fallo, accederá a la bitácora. La bitácora suele proporcionar toda la información necesaria para averiguar la causa del fallo. Lea por todas las bitácoras e intente averiguar por qué se produce el fallo y, a continuación, haga lo necesario para resolverlo.

Ocasionalmente, una comprobación CI fallará por razones no relacionadas con sus cambios. Esto podría deberse a una incidencia en la máquina que ejecuta la comprobación CI; o porque una comprobación CI es inestable. Si ve un fallo, y está seguro de que no está relacionado con sus cambios, añada un comentario a su PR a tal efecto, y lo investigaremos.

Para desencadenar una ejecución nueva de IC, debe subir los cambios nuevos a su rama.

Si te encuentras en una situación en donde necesitas obtener ayuda para obtener IC pase, déjanos un comentario en el RP haciéndonoslo saber y haremos lo que podamos para ayudarte.

Las comprobaciones pre-commit y towncrier

Si las comprobaciones pre-commit o towncrier fallan, se bloqueará la ejecución del resto de las comprobaciones de CI. Tendrás que resolver las incidencias aplicables antes de que se ejecute el conjunto completo de comprobaciones.

Tenemos recursos limitados de IC. Es importante entender que cada vez que empuje a la rama, IC se iniciará. Si vas a hacer una serie de cambios, es mejor hacer esos cambios a nivel local, subirlos a todos a la vez. IC sólo se ejecutará en la confirmación más reciente en un lote, minimizando la carga en nuestro sistema de IC.

El proceso de envío de su RP no finaliza hasta que pasa IC, o puede proporcionar una explicación de por qué no lo hace.

Es posible que tu solicitud de extracción requiera contenido adicional, tal como una nota de cambios, antes que pueda ser revisada.