Implementación de una nueva función¶

Una vez concluido el proceso de propuesta, deberías tener un diseño completo para una nueva función. Eso significa que es hora de empezar a escribir.

Si su función requiere una implementación específica para una plataforma, el proceso de propuesta debería haber validado que la idea podría implementarse en todas las plataformas. Sin embargo, como persona que implementa una nueva función por primera vez, no eres responsable de implementarla en todas las plataformas. Necesitas proporcionar una implementación completa para al menos una plataforma, incluyendo pruebas. Para cualquier otra plataforma, tendrás que proporcionar una implementación "stub" - una implementación que proporciona la definición de interfaz desnuda, pero genera un NotImplementedError o muestra un mensaje de registro de que el comportamiento no está implementado en esa plataforma.

Una parte importante de la implementación de una nueva función es asegurarse de que esté completamente documentada. Como mínimo, esto significa asegurarse de que existe documentación sobre la API, pero también puede ser necesario añadir una guía práctica o temática.

Aportación de nuevas funciones¶

Configurar un entorno de desarrollo

Contribuir a BeeWare requiere que configures un entorno de desarrollo.

Requisitos previos¶

Necesitarás instalar los siguientes requisitos previos.

macOSLinuxWindows

{{ nombre_formal }} requiere Python 3.10+. También necesitarás un método para gestionar entornos virtuales (como venv).

Puede verificar la versión de Python que tiene instalada ejecutando:

$ python3 --version

Si tiene más de una versión de Python instalada, es posible que tenga que sustituir python3 por un número de versión específico (por ejemplo, python{{ versión_python_reciente }}).

Recomendamos evitar las versiones recientes de Python (es decir, las versiones que tienen un micro número de versión ".0" o ".1", como por ejemplo, 3.14.0). Esto se debe a que las herramientas necesarias para soportar Python en macOS a menudo no están disponibles para las versiones estables de Python publicadas recientemente.

{{ nombre_formal }} requiere Python 3.10+. También necesitarás un método para gestionar entornos virtuales (como venv).

Puede verificar la versión de Python que tiene instalada ejecutando:

$ python3 --version

Si tiene más de una versión de Python instalada, es posible que tenga que sustituir python3 por un número de versión específico (por ejemplo, python{{ versión_python_reciente }}).

Recomendamos evitar las versiones recientes de Python (es decir, las versiones que tienen un micro número de versión ".0" o ".1", como por ejemplo, 3.14.0). Esto se debe a que las herramientas necesarias para soportar Python en Linux a menudo no están disponibles para las versiones estables de Python recientemente publicadas.

{{ nombre_formal }} requiere Python 3.10+. También necesitarás un método para gestionar entornos virtuales (como venv).

Puede verificar la versión de Python que tiene instalada ejecutando:

C:\...>py -3 --version

Si tiene más de una versión de Python instalada, puede que necesite sustituir -3 por un número de versión específico (por ejemplo, -python3.13).

Recomendamos evitar las versiones recientes de Python (es decir, las versiones que tienen un micro número de versión ".0" o ".1", como por ejemplo, 3.14.0). Esto se debe a que las herramientas necesarias para soportar Python en Windows a menudo no están disponibles para las versiones estables de Python recientemente publicadas.

Configure su entorno de desarrollo¶

La forma recomendada de configurar tu entorno de desarrollo para BeeWare es utilizar un entorno virtual, y luego instalar la versión de desarrollo de BeeWare y sus dependencias.

Clonar el repositorio BeeWare¶

A continuación, ve a la página BeeWare de GitHub y, si aún no lo has hecho, bifurca el repositorio en tu propia cuenta. A continuación, haz clic en el botón "<> Code" de tu bifurcación. Si tienes la aplicación de escritorio de GitHub instalada en tu ordenador, puedes seleccionar "Abrir con GitHub Desktop"; si no, copia la URL HTTPS proporcionada, y utilízala para clonar el repositorio en tu ordenador utilizando la línea de comandos:

macOSLinuxWindows

Fork el repositorio BeeWare, y luego:

$ git clone https://github.com/<your username>/beeware.git

(sustituyendo tu nombre de usuario de GitHub)

Fork el repositorio BeeWare, y luego:

$ git clone https://github.com/<your username>/beeware.git

(sustituyendo tu nombre de usuario de GitHub)

Fork el repositorio BeeWare, y luego:

C:\...>git clone https://github.com/<your username>/beeware.git

(sustituyendo tu nombre de usuario de GitHub)

Crear un entorno virtual¶

Para configurar un entorno virtual y actualizar pip, ejecute:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Tu prompt debería tener ahora un prefijo (.venv) delante.

Instalar BeeWare¶

Ahora que tienes el código fuente, puedes hacer una instalación editable de {{ nombre_formal }} en tu entorno de desarrollo. Ejecute el siguiente comando:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Activar precommit¶

BeeWare utiliza una herramienta llamada pre-commit para identificar problemas simples y estandarizar el formato del código. Para ello, instala un hook git que ejecuta automáticamente una serie de linters de código antes de finalizar cualquier commit git. Para activar pre-commit, ejecuta:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

¡Ahora estás listo para empezar a hackear BeeWare!

Trabajar desde una sucursal

Antes de empezar a trabajar en su cambio, asegúrese de que ha creado una rama. Por defecto, cuando clonas la bifurcación de tu repositorio, serás chequeado en tu rama main. Esta es una copia directa de la rama main de BeeWare.

Aunque puedes enviar un pull request desde tu rama principal, es preferible que no lo hagas. Si envías un pull request que es casi correcto, el miembro del equipo central que revise tu pull request podrá hacer los cambios necesarios, en lugar de dar feedback pidiendo un cambio menor. Sin embargo, si envía su pull request desde su rama main, se impide a los revisores hacer modificaciones.

Trabajar a partir de tu rama principal también dificulta las cosas para tú después de completar tu primer pull request. Si quieres trabajar en un segundo pull request, necesitarás tener una copia "limpia" de la rama principal del proyecto upstream en la que basar tu segunda contribución; si has hecho tu primera contribución desde tu rama principal, ya no tienes esa versión limpia disponible.

En su lugar, deberías hacer tus cambios en una rama de características. Una rama de características tiene un nombre simple para identificar el cambio que has hecho. Por ejemplo, si estás corrigiendo un error que causa problemas de compilación en Windows 11, puedes crear una rama de características fix-win11-build. Si el error está relacionado con un problema específico del que se ha informado, también es habitual hacer referencia al número de problema en el nombre de la rama (por ejemplo, fix-1234).

Para crear una rama de características fix-win11-build, ejecute:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Evitar la desviación del alcance

El "Scope creep" se produce cuando la lista de problemas resueltos o funcionalidades implementadas por una única contribución crece significativamente más allá de lo que se pretendía cuando se inició el trabajo. Empiezas con un simple problema, descubres otro estrechamente relacionado y decides incluir también esa solución, luego una tercera… antes de que te des cuenta, tienes un pull request que cierra 5 problemas y añade 3 nuevas funcionalidades, incluyendo docenas de archivos.

El desvío del alcance le ocurre a todo el mundo. Es un concepto demasiado familiar para los desarrolladores experimentados; todos lo hemos hecho varias veces y hemos sufrido los problemas que conlleva.

Hay razones muy prácticas para evitar la ampliación del ámbito de aplicación. Cuanto mayor sea una contribución, más difícil será trabajar con ella. Se hace más difícil identificar los casos extremos o los problemas potenciales, lo que significa que la calidad general de la contribución puede disminuir. Las revisiones también se vuelven más difíciles cuando el revisor tiene que tratar con múltiples contextos potencialmente no relacionados. Una contribución más grande significa más comentarios de revisión, y como contribuyente, puede llegar a ser difícil seguir múltiples hilos de revisión. Incluso tu experiencia en GitHub se verá afectada: la interfaz de usuario de GitHub se ralentizará a medida que aumente el tamaño de un PR, lo que significa que navegar por los archivos a través de la interfaz de GitHub e intentar dejar comentarios de revisión será cada vez más difícil.

Cada vez que encuentres una razón para añadir algo a tu contribución que no forme parte explícita de la propuesta original o del informe de errores, deberías plantearte si estás entrando en un proceso de ampliación del alcance. ¿Hay dos funciones distintas que podrían implementarse por separado? ¿Podría implementarse una función con una limitación o error conocidos, y arreglar ese error en un pull request posterior? ¿Una parte de la corrección de un error es independiente de otra? Si parte de un cambio puede omitirse sin alterar la contribución original, probablemente debería hacerse.

El desarrollo de software es siempre un proceso de mejora incremental. Cada contribución individual debe dejar la base de código en un mejor estado como resultado de ser fusionado, pero es totalmente aceptable dejar errores o partes de características como trabajo para futuras mejoras. Eso puede significar dividir una solicitud de extracción en varias partes que puedan revisarse de forma independiente, o registrar un problema para que otra persona pueda investigarlo y resolverlo.

Limitar el alcance de cada contribución ayuda a todos los implicados, incluido usted. Tus revisores, e incluso tú mismo, lo agradecerán.

Implementar la nueva función

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOTAL 7540 0 1040 0 100,0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Name Stmts Miss Branch BrPart Cover Missing
--------------------------------------------------------------------------------
src/some/archivo_interesante.py 111 1 26 0 98,1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
TOTAL 7540 1 1726 0 99,9

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

(.venv) $ tox p -m prueba-plataforma

(.venv) $ tox p -m prueba-plataforma

(.venv) C:\...>tox p -m prueba-plataforma

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

(.venv) $ tox -e cobertura-plataforma-html

(.venv) $ tox -e cobertura-plataforma-html

(.venv) C:\...>tox -e cobertura-plataforma-html

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | Crear documentación

Antes de realizar cualquier cambio en la documentación de BeeWare, es
útil confirmar que se puede construir la documentación existente.



Usted **debe** tener un intérprete de Python 3.13 instalado
y disponible en su ruta (es decir, `python3.13` debe
iniciar un intérprete de Python 3.13).

{{ nombre_formal }} utiliza `tox` para construir la documentación. Los
siguientes comandos `tox` deben ejecutarse desde la misma ubicación que el
archivo `tox.ini`, que se encuentra en el directorio raíz del proyecto.

### Vista previa de la documentación en directo

Para facilitar la edición rápida de la documentación, BeeWare dispone
de un modo de "vista previa en directo".

/// warning | ¡La vista previa en vivo se generará con advertencias!

El live serve está disponible para iterar sobre las actualizaciones de tu
documentación. Mientras estás en el proceso de actualizar cosas, puedes
introducir un problema de marcado. Los problemas considerados como "ADVERTENCIA"
harán que la compilación estándar falle, sin embargo, el live serve está
configurado para indicar advertencias en la salida de la consola, mientras
continúa la compilación. Esto le permite iterar sin necesidad de reiniciar la
vista previa en vivo.

Un `WARNING` es diferente de un `ERROR`. Si introduce un problema que se
considera un `ERROR`, el servicio en directo fallará y será necesario
reiniciarlo. No se reiniciará hasta que se resuelva el problema `WARNING`.

///

Para iniciar el servidor en vivo:



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Esto creará la documentación, iniciará un servidor web para servir la documentación y vigilará el sistema de archivos para detectar cualquier cambio en el origen de la documentación.

Una vez iniciado el servidor, verá algo como lo siguiente en la salida de la consola:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Abra un navegador y vaya a la URL indicada. Ahora puede empezar a iterar sobre la documentación. Si se detecta un cambio, la documentación se reconstruirá y cualquier navegador que vea la página modificada se actualizará automáticamente.

docs-live es un primer paso

Ejecutar docs-live para trabajar con el servidor en vivo es para la iteración inicial. Usted debe siempre ejecutar una compilación local antes de enviar un pull request.

Construcción local¶

Una vez que hayas terminado de iterar, tendrás que hacer una compilación local de la documentación. Este proceso de compilación está diseñado para fallar si hay algún problema de marcado. Esto le permite detectar cualquier cosa que podría haber perdido con el servidor en vivo.

Generación de una compilación local¶

Para generar una compilación local:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

La salida de esta compilación estará en el directorio _build en la raíz del proyecto.

Generación de una compilación local traducida¶

La documentación de BeeWare está traducida a varios idiomas. Las actualizaciones de la documentación en inglés pueden provocar problemas en las versiones en otros idiomas. Es importante verificar que todas las versiones funcionan antes de enviar un pull request.

Para generar una compilación de todas las traducciones disponibles:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

El resultado de la compilación de cada idioma estará en el directorio asociado _build/html/<languagecode>, donde <languagecode> es el código de idioma de dos o cinco caracteres asociado al idioma específico (por ejemplo, fr para el francés, it para el italiano, etc.).

Si encuentra un problema con una sola compilación, puede ejecutar esa compilación por separado ejecutando tox -e docs-<languagecode>. Por ejemplo, para compilar sólo la documentación en francés, ejecute:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

La salida de una compilación en un solo idioma estará en el directorio _build.

Documentación¶

El proceso de compilación identificará los problemas de Markdown, pero BeeWare realiza algunas comprobaciones adicionales de estilo y formato, conocidas como "linting". Para ejecutar las comprobaciones de lint:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Esto validará la documentación no contiene:

hipervínculos muertos
palabras mal escritas

Si se identifica una palabra válida como mal escrita, añádala a la lista de docs/spelling_wordlist. Esto añadirá la palabra al diccionario del corrector ortográfico. Al añadir a esta lista, recuerde:

Preferimos la ortografía estadounidense, con algunas libertades para el coloquialismo específico de la programación (por ejemplo, "apps") y la verbosidad de los sustantivos (por ejemplo, "scrollable").
Cualquier referencia al nombre de un producto debe utilizar la mayúscula preferida del producto. (por ejemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un término se utiliza "como código", debe citarse como literal (como esto) en lugar de añadirlo al diccionario.

///

Redactar documentación

Estos son los pasos que debe seguir para escribir su contribución a la documentación de BeeWare.

Actualización de la documentación existente¶

Si está editando la documentación existente, tendrá que localizar el archivo en el directorio /docs/en. La estructura del archivo sigue la estructura de la página, por lo que puede localizar el archivo utilizando la URL de la documentación.

Añadir nueva documentación¶

Si está añadiendo un nuevo documento, hay algunos pasos más.

Deberá crear el documento en la ubicación adecuada dentro del directorio docs/es. A modo de ejemplo, diremos que está añadiendo un nuevo documento con el nombre nuevo_doc.md.

A continuación, tendrás que actualizar el archivo docs/es/SUMMARY.md para incluir tu nuevo archivo. El archivo SUMMARY.md está organizado para reflejar básicamente la estructura de directorios de docs/es, pero, lo que es más importante, determina directamente la estructura de la barra lateral izquierda. Si localizas la sección donde pretendes incluir nuevo_doc.md, no necesitas cambiar nada en SUMMARY.md si ves una ruta comodín listada. Por ejemplo:

- ./path/to/directory/*

Si la sección en la que pretende incluir nuevo_doc.md es una lista de enlaces Markdown individuales, tendrá que añadir un enlace explícito al suyo. Por ejemplo:

- [My new document](new_doc.md)

Redactar la documentación¶

Ahora puede abrir el archivo deseado en su editor y empezar a escribir.

Disponemos de una guía de estilo de la documentación que describe nuestras directrices para escribir documentación para BeeWare.

Añadir una nota de cambio

Muchas herramientas de BeeWare utilizan towncrier para ayudar a construir las notas de cada versión. Cuando envíe un pull request a una de las herramientas aplicables, deberá incluir una nota de cambio - esta nota de cambio se convertirá en la entrada de las notas de la versión que describe el cambio que se ha realizado.

Cada pull request debe incluir al menos un archivo en el directorio changes/ que proporcione una breve descripción del cambio implementado por la pull request. La nota de cambio debe estar en formato Markdown, en un archivo cuyo nombre tenga el formato <id>.<tipo de fragmento>.md. Si el cambio que propone corregirá un error o implementará una característica para la que existe un número de incidencia, el ID será el número de ese ticket. Si el cambio no tiene la incidencia correspondiente, se puede utilizar el número de PR como ID. No sabrá este número de PR hasta que envíe la solicitud de extracción, por lo que la primera pasada de CI fallará en la comprobación del towncrier; añada la nota de cambio y envíe una actualización del PR y CI debería entonces pasar.

Existen cinco tipos de fragmentos:

Característica El PR añade un nuevo comportamiento o capacidad que antes no era posible (por ejemplo, añadir soporte para un nuevo formato de empaquetado, o una nueva característica en un formato de empaquetado existente);
Corrección de errores: El PR corrige un error en la implementación existente;
doc: El PR es una mejora significativa de la documentación;
removal; El PR representa un cambio incompatible hacia atrás en la BeeWare API; o
misc; Un cambio menor o administrativo (por ejemplo, la corrección de un error tipográfico, una aclaración lingüística menor o la actualización de una versión de dependencia) que no necesita anunciarse en las notas de la versión.

Esta descripción en la nota de cambio debe ser un resumen de "marketing" de alto nivel del cambio desde la perspectiva del usuario, no una descripción técnica profunda o detalles de implementación. Es distinto de un mensaje de confirmación: un mensaje de confirmación describe lo que se ha hecho para que los futuros desarrolladores puedan seguir el razonamiento de un cambio; la nota de cambio es una descripción en beneficio de los usuarios, que pueden no tener conocimientos internos.

Por ejemplo, si se corrige un error relacionado con el nombre del proyecto, el mensaje de confirmación puede ser el siguiente:

Aplique una comprobación de expresión regular más fuerte para no permitir nombres de proyecto que empiecen por dígitos.

La nota de cambio correspondiente diría algo así

Los nombres de los proyectos ya no pueden empezar por un número.

Algunos PR introducirán múltiples características y corregirán múltiples errores, o introducirán múltiples cambios incompatibles con versiones anteriores. En ese caso, el RP puede tener varios archivos de notas de cambio. Si necesita asociar dos tipos de fragmentos con el mismo ID, puede añadir un sufijo numérico. Por ejemplo, si el RP 789 añadió una característica descrita por el ticket 123, cerró un fallo descrito por el ticket 234, y también hizo dos cambios incompatibles hacia atrás, podría tener 4 archivos de notas de cambio:

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

Para obtener más información sobre towncrier y los tipos de fragmentos, consulte Fragmentos de noticias. También puedes ver ejemplos existentes de fragmentos de noticias en el directorio changes del repositorio BeeWare. Si esta carpeta está vacía, es probable que se deba a que {{ nombre_del_proyecto }} ha publicado recientemente una nueva versión; los archivos de notas de cambio se eliminan y se combinan para actualizar las notas de la versión con cada versión. Puedes mirar ese archivo para ver el estilo de comentario que se requiere; puedes mirar recently merged PRs para ver cómo formatear tus notas de cambio.

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:

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 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.

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 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.

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, 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.