Solucionar una incidencia

BeeWare sigue un listado de incidencia conocida. Cualquiera de estos problemas es susceptible de ser abordado.

Esta lista puede filtrarse de varias maneras. Por ejemplo, puede filtrar por plataforma, para centrarse en las incidencias que afectan a las plataformas en las que puede realizar incidencias; o puede filtrar por tipo de incidencia, como fallos de documentación. También hay un filtro para buenas primeras ediciones: se trata de incidencias que se han identificado como problemas con una causa conocida, y creemos que la solución debería ser relativamente sencilla (aunque podríamos equivocarnos en nuestro análisis).

Si una incidencia tiene más de 6 meses, es muy posible que la incidencia ya se haya resuelto, por lo que el primer paso es comprobar que puede reproducirlo. Utilice la información proporcionada en el informe de fallo para intentar reproducir el problema. Si no puedes reproducir el problema, informa de lo que has encontrado como un comentario sobre la incidencia, y elige otra incidencia.

Si puedes reproducir el problema, intenta solucionarlo. Averigua qué combinación de código está implementando la función y averigua qué es lo que no funciona correctamente.

Incluso si no puedes solucionar el problema, vale la pena informar de cualquier cosa que descubras durante el proceso como comentario sobre la incidencia. Si puedes encontrar el origen del problema, pero no la solución, ese conocimiento será a menudo suficiente para que alguien que sepa más sobre una plataforma resuelva el problema. Si la incidencia ya no ofrece un buen caso de reproducción (una pequeña aplicación de ejemplo que no haga más que reproducir el problema), proporcionar uno puede ser de gran ayuda.

Contribuir a la solución de una incidencia

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 (tal como venv).

Puedes verificar la versión de Python que tienes 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 (p.ej., python{{ versión_python_reciente }})

Recomendamos evitar las versiones recientes de Python (e.d., las versiones que tienen un micro número de versión ".0" o ".1", como p.e., 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 recientemente publicadas.

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

Puedes verificar la versión de Python que tienes 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 (p.ej., python{{ versión_python_reciente }})

Recomendamos evitar las versiones recientes de Python (e.d., las versiones que tienen un micro número de versión ".0" o ".1", como p.ej., 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 (tal como venv).

Puedes verificar la versión de Python que tienes instalada ejecutando:

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

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

Recomendamos evitar las versiones recientes de Python (e.d., las versiones que tienen un micro número de versión ".0" o ".1", como p.ej., 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.

Configura tu 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, pulsa en el botón "<> Code" de tu bifurcación. Si tienes instalada la aplicación de escritorio de GitHub en tu equipo, puedes seleccionar "Abrir con GitHub Desktop"; en otro caso, copia la URL HTTPS proporcionada, y utilízala para clonar el repositorio en tu equipo utilizando la línea de comandos:

macOSLinuxWindows

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Establecer un repositorio ascendente

Tras clonar tu bifurcación, añade el repositorio BeeWare como un upstream remoto. Esto le da a tu clon local una referencia al repositorio original, haciéndolo más fácil sincronizar actualizaciones a lo largo del tiempo.

También necesitarás etiquetas desde upstream tales que las herramientas como Toga y Briefcase puedan resolver números de versión precisos:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Si quieres que tu bifurcación también incluya esas etiquetas, puedes subirlas a:

$ git push --tags

Esto puede ser útil si más adelante creas un nuevo clon y deseas que las etiquetas estén disponibles desde tu bifurcación.

Crea un entorno virtual

Para configurar un entorno virtual y subir la versión de 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 solicitud ahora tendría un prefijo (.venv) delante.

Instalar BeeWare

Ahora que tienes el código fuente, puedes hacer una instalación editable de BeeWare 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 pre‐commit

BeeWare utiliza una herramienta llamada pre-commit para identificar incidencias 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 que ha creado una rama. Por defecto, cuando clonas tu bifurcación del repositorio, serás chequeado en tu rama main. Ésta es una copia directa de la rama main de BeeWare.

Mientras puedas 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 comentarios 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 ti 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 disponible esa versión limpia.

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

Para crear una rama de prestaciones 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

Reproduce la incidencia

No se puede solucionar un problema si no se tiene el problema en primer lugar. Por tanto, reproducir la incidencia es un requisito previo para solucionarlo. En software, los problemas suelen denominarse "bugs", y las incidencias, "informes de fallos".

Alguien ha informado de un fallo. Necesitas validar que los pasos que describe el informador dan como resultado el fallo del que se informa. ¿Puedes reproducir el mismo resultado haciendo exactamente lo que fue descrito en el informe? Si no puedes, tienes que averiguar por qué.

Fallos en el código

En una situación ideal, tendrás la misma configuración que la persona que informó del fallo, seguirás los pasos y podrás reproducir el fallo tal y como se describe. En muchos casos, sin embargo, no será tan sencillo. Muchos informes de fallos sólo incluyen explicaciones vagas y un conjunto de condiciones vago. El problema es que muchos fallos varían en función del conjunto de condiciones implicadas, incluyendo como se interactúa con ellos, varias condiciones previas, el sistema operativo, la versión del sistema operativo, la arquitectura de la CPU, o si la máquina del usuario es antigua y lenta o nueva y rápida. Cuanta más información tengamos sobre la situación que rodea al fallo, mejor. Intenta reproducir el conjunto de condiciones que te ha proporcionado el informador. Si no puedes hacerlo, puede que tu siguiente paso sea solicitar más información a la persona que ha informado del fallo.

La mejor forma de reproducir un fallo es con el ejemplo más pequeño posible que muestre la incidencia. La mayoría de las veces los informadores no proporcionarán un ejemplo mínimo viable; si proporcionan algún ejemplo, será copiado directamente de su aplicación del "mundo real". Tu propósito será reducir el informe a la forma más simple posible que exhiba la incidencia. El mejor caso de reproducción es el programa más pequeño posible. Esta reducción es útil en sí misma porque determina cuál es el problema real. Cualquiera puede tomar el ejemplo mínimo, ejecutarlo y observará el fallo que se describe.

Fallos en la documentación

Los defectos en la documentación pueden manifestarse de diferentes maneras. Hay problemas de formato que dan lugar a representar incidencias. A veces ni siquiera se trata de un fallo; la persona puede haber leído mal la documentación o haber cometido una equivocación genuino. Esto no significa necesariamente que no haya una incidencia con la documentación. El contenido puede ser poco claro o impreciso y dar lugar a confusiones o malas interpretaciones. Es posible que un concepto que debería tratarse no se trate, porque está completamente indocumentado.

Cuando se archiva un error por una incidencia de documentación, querrá verificar que la incidencia notificada sigue existiendo realmente. En el caso de las incidencias de representación tendrá que crear la documentación para ver si puede reproducir la incidencia. Las incidencias del contenido son una cuestión de lectura para verificar que nadie ha enviado una actualización.

Actualizar la incidencia

El último paso en el proceso de triaje es documentar los resultados dejando un comentario sobre la incidencia.

Si eres capaz de reproducir la incidencia exactamente como se describe, eso es todo lo que necesitas decir. Deja un comentario diciendo que has confirmado que tienes el mismo problema, exactamente como lo describe el informe original.

Si puedes aportar algún contexto adicional, incluye los detalles de ese contexto. Esto podría incluir la posibilidad de reproducir el problema en un sistema operativo diferente, o con una versión distinta de alguno de los programas implicados, o cualquier otra cosa que varíe con respecto al informe original.

Si al informe original le faltaban detalles que usted necesitaba para reproducirlo, incluya esos detalles. Esto podría incluir detalles sobre el sistema operativo o la versión que el informe original no incluía, bitácoras o trazas de pila más completos, o instrucciones más claras sobre la secuencia exacta de operaciones necesarias para reproducir el problema. Si has desarrollado una forma más sencilla de reproducir el problema (o el informador original no proporcionó un caso de reproducción), puedes incluir detalles de esa metodología de reproducción.

Si no puede reproducir la incidencia también deje un comentario detallando lo que ha intentado. Saber dónde no existe un problema es casi tan importante como saber dónde sí existe, ya que eso ayuda a reducir las posibles causas. Si tienes alguna teoría sobre por qué no puedes reproducir el problema (por ejemplo, si crees que se trata de un error de uso o que el problema se ha resuelto con una actualización reciente del sistema operativo), incluye esa especulación en tu comentario.

Por último, puede hacer recomendaciones al equipo central. Si cree que el informe original es erróneo, sugiera que se cierre la incidencia; si tiene una teoría sobre la causa de la incidencia, también puede sugerirla. Sus comentarios ayudarán al equipo central a decidir cómo avanzar en la resolución de la incidencia.

Si la solución de la incidencia requiere cambios en el código:

Escribir, ejecutar y probar código

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.

///

**Si la solución de la incidencia requiere cambios en la documentación:**

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



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

BeeWare utiliza `tox` para construir la documentación. Las
instrucciones de `tox` siguientes deben ser ejecutadas desde el mismo lugar que
el archivo `tox.ini`, el cual está dentro del directorio raíz del proyecto.

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

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 directo se generará con advertencias!

El servidor en vivo está disponible para iterar sobre las actualizaciones de tu
documentación. Mientras estás en el proceso de actualizar cosas, puedes
introducir una incidencia de marcado. Las incidencias consideradas como
`ADVERTENCIA` harán que la compilación estándar falle, sin embargo, el servidor
en vivo 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 directo.

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

///

Para iniciar el servidor en directo:



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

Abre un navegador, y ve a la URL proporcionada. Ahora puedes empezar a iterar sobre la documentación. Si se detecta un cambio, la documentación será reconstruida y cualquier navegador que vea la página modificada se recargada automáticamente.

/// nota | docs-live es un paso inicial

Ejecuta docs-live para funcionar con el servidor en directo está pensado para la iteración inicial. Tú debes ejecutar siempre 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 habría perdido con el servidor en directo.

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

Generar 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 incidencias 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 (p.ej., fr para el francés, it para el italiano, etc.).

Si encuentra una incidencia con una sola compilación, puede ejecutar esa compilación separadamente ejecutando tox -e docs-<languagecode>. Por ejemplo, para compilar solo 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 "hilado". Para ejecutar las comprobaciones de hilado:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

Esto validará la documentación que no contiene:

• hiperenlaces muertos
• palabras mal escritas

Si se identifica un deletreo de 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 este listado, recuerda:

• Preferimos la deletreo estadounidense, con algunas libertades para el coloquialismo específico de la programación (p.ej., "apps") y la verborrea de los sustantivos (p.ej., "scrollable")
• Cualquier referencia a un nombre de producto utilizaría la capitalización preferida del producto. (p.ej., “macOS”, “GTK”, “pytest”, “Pygame”, “PyScript”).
• Si un término se utiliza «como código», debe citarse como un literal (como esto) en lugar de ser añadido 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.

Cuando esté listo para enviar su contribución:

Añadir una nota de cambio

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

Cada solicitud de extracción 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>.<fragment type>.md. Si el cambio que propone corregirá un error o implementará una prestación 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 RP 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 RP e IC debería entonces pasar.

Hay cinco tipos de fragmentos:

• prestación: El RP añade un comportamiento nuevo o capacidad que antes no era posible (p.ej., añadir mantenimiento para una formato nueva de empaquetado, o una prestación nueva en un formato de empaquetado existente);
• bugfix:El RP corrige un fallo en la implementación existente;
• doc: El RP es una mejora significativa para la documentación;
• removal; El RP representa un cambio hacia atrás incompatible en el API BeeWare; o
• misc; Un cambio menor o administrativo (p.ej., corregir una tipografía, una aclaración lingüística menor, o actualizar una versión de dependencia) que no necesite anunciarse en las notas de la versión.

Esta descripción en la nota de cambio sería un sumario “mercantil” 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 fallo 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 leería algo así como:

Los nombres del proyecto ya no pueden más comenzar con un número.

Algunos de los RP introducirán múltiples prestaciones y corregirán múltiples fallos, 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 adjuntar un sufijo numérico. Por ejemplo, si el RP 789 añadió una prestación 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 versión nueva; 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 los RP fundidos recientemente 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 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.