Saltar a contenido

Enviar una solicitud de extracción

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

Trabajar con precommit

Al confirmar cualquier cambio, se ejecutará automáticamente la precompromiso. Si se encuentra algún problema 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 un problema de formato de código:

(.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 al envío y volver a enviar el cambio. Sin embargo, algunas comprobaciones requerirán que realices modificaciones manuales. Una vez que haya hecho esos cambios, vuelva a añadir los archivos modificados y vuelva a confirmar.

(.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 enviar a GitHub.

Sube tus cambios a GitHub y crea tu pull request

La primera vez que hagas un push a GitHub, se te proporcionará una URL que te llevará directamente a la página de GitHub para crear un nuevo pull request. 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.

(.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, no volverás a recibir la URL. Sin embargo, hay otras formas de acceder a la URL de creación del RP:

  • Navegue hasta el repositorio upstream, haga clic en "Pull Requests" seguido de "New pull request", y elija el desde el que desea enviar su pull request.
  • Si has hecho push recientemente, navega al repositorio upstream, localiza el banner encima de la lista de archivos que indica que el repositorio ha "tenido push recientes", y pulsa el botón "Comparar & pull request".
  • Utiliza el comando gh pr create de la CLI de GitHub y rellena los campos.
  • Utiliza el comando de la CLI de GitHub gh pr create --web para abrir un navegador web en la página de creación del RP.

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

La CLI de GitHub: gh

GitHub proporciona la GitHub CLI, que te da acceso a muchas de las características de GitHub desde tu terminal, a través del comando gh. La Documentación de la CLI de GitHub cubre todas las características.

Contenido de la solicitud de extracción

El título de una pull request 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 PR debe dar a una persona sin ningún contexto una idea razonablemente sólida de qué bug o característica se implementa en tu PR.

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 PR, debe explicarse e incluirse en el PR. La explicación debe incluir cómo ejecutarlos y qué hacer para reproducir el resultado deseado.

Si su pull request va a resolver el problema #1234, debe incluir el texto `Fixes

1234` en la descripción de su pull request. Esto hará que el problema 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 CI, es el proceso de ejecutar comprobaciones automatizadas en tu pull request. Esto puede incluir comprobaciones sencillas, como asegurarse de 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 el problema.

Cuando CI falla, los enlaces de fallo aparecerán en la parte inferior de la página PR, bajo el título "Algunas comprobaciones no tuvieron éxito". Verá una lista de comprobaciones fallidas, que aparecerá en la parte superior de la lista de todas las comprobaciones si también hay comprobaciones correctas. Si hace clic en el enlace del fallo, accederá al registro. El registro suele proporcionar toda la información necesaria para averiguar la causa del fallo. Lea el registro 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 un problema 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 nueva ejecución de CI, debe enviar nuevos cambios a su rama.

Si te encuentras en una situación en la que necesitas ayuda para conseguir que la IC pase, déjanos un comentario en el PR 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 los problemas aplicables antes de que se ejecute el conjunto completo de comprobaciones.

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

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

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