Saltar a contenido

Implementación de una nueva función

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

Si su prestación requiere una implementación específica para una plataforma, el proceso de propuesta debería haber validado que la idea pudo implementarse en todas las plataformas. Sin embargo, como persona que implementa una prestación nueva por primera vez, no eres responsable de implementar la prestación 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 de esbozo: una implementación que proporciona la definición de interfaz básica, pero genera un NotImplementedError o extrae un mensaje de bitácora que el comportamiento no está implementado en esa plataforma.

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

Aportación de nuevas funcionalidades

Declarar un entorno de desarrollo

Configuración de un entorno de desarrollo

Contribuir a BeeWare Docs Tools requiere que configures un entorno de desarrollo.

Requisitos previos

Necesitarás instalar los siguientes requisitos previos.

{{ 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 Docs Tools es utilizar un entorno virtual, y luego instalar la versión de desarrollo de BeeWare Docs Tools y sus dependencias.

Clonar el repositorio BeeWare Docs Tools

A continuación, ve a la página BeeWare Docs Tools 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:

Bifurca el repositorio BeeWare Docs Tools, y luego:

$ git clone https://github.com/<tu-nombre-de-usuario>/beeware-docs-tools.git

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare Docs Tools, y luego:

$ git clone https://github.com/<tu-nombre-de-usuario>/beeware-docs-tools.git

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare Docs Tools, y luego:

C:\...>git clone https://github.com/<tu-nombre-de-usuario>/beeware-docs-tools.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:

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

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

C:\...>git remote add upstream https://github.com/beeware/beeware-docs-tools.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:

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

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

C:\...>cd beeware-docs-tools
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 Docs Tools

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

(.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 Docs Tools 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:

(.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 Docs Tools!

Trabajar desde una rama

Trabaja desde una rama de características, no desde tu rama main.

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

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 prestación. 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 prestación fix-win11-build, ejecute:

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

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

(.venv) C:\...>git switch -c fix-win11-build
Evitar arrastrarse en el ámbito

Evitar la desviación del alcance

El "Scope creep" se produce cuando la lista de problemas resueltos o prestaciones implementadas por una única contribución crece significativamente más allá de lo que se pretendía cuando se inició el trabajo. Empiezas con una simple incidencia; descubres un problema relacionado estrechamente, y decides incluir esa reparación; luego una tercera… antes de que te des cuenta, tienes una solicitud de extracción que cierra 5 incidencias y añade 3 prestaciones nuevas, 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 las incidencias 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. ¿Pudo implementarse dos prestaciones distintas por separado? ¿Pudo implementarse una prestación con una limitación o defecto conocidos, y solucionar ese defecto en una solicitud de extracción posterior? ¿Una parte de la corrección de un defecto 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 dejaría la base de código en un mejor estado como resultado de ser fusionado, pero es totalmente aceptable dejar fallos o partes de prestaciones como trabajo para futuras mejoras. Eso puede significar separar una solicitud de extracción en varias partes que puedan revisarse de forma independiente, o realizar una bitácora de incidencia tal que otra persona pueda investigarlo y resolver el problema.

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 prestación nueva

Escribir, ejecutar y probar código.

Para corregir un defecto o implementar una característica, requerirá escribir algún código nuevo.

Para empezar a trabajar en el código, asegúrate de tener un entorno de desarrollo configurado y de estar trabajando en una rama.

Contamos con una guía de estilo de código que describe nuestras directrices para escribir código para BeeWare.

Desarrollo dirigido en pruebas

Una buena forma de asegurarte de que tu código va a funcionar como esperas es escribir primero un caso de prueba para comprobarlo. Este caso de prueba debería fallar al principio, ya que el código que se está probando aún no existe. A continuación, puedes introducir los cambios necesarios en el código para que la prueba pase, y así saber que lo que has escrito resuelve el problema tal y como esperabas.

Ejecuta tu código

Una vez escrito el código, debes asegurarte que funciona. Tendrás que ejecutarlo manualmente para comprobar que hace lo que esperas. Si aún no lo has hecho, te conviene escribir un caso de prueba para tus cambios; como se ha mencionado anteriormente, esta prueba debería fallar si el código está comentado o no está presente.

Añadirás tu caso de prueba al conjunto de pruebas, para que se pueda ejecutar junto con el resto de pruebas. El siguiente paso es ejecutar el conjunto de pruebas.

Ejecución de pruebas y cobertura

BeeWare Docs Tools utiliza tox para gestionar el proceso de pruebas y pytest para su propio conjunto de pruebas.

El comando tox predeterminado incluye ejecutar:

  • ganchos de pre-commit
  • towncrier emite nota de comprobante

  • relaciona la documentación

  • conjunto de pruebas para las versiones disponibles de Python

  • informes de cobertura de código

Esto es esencialmente que ejecuta IC cuando envías una solicitud de Incorporación de Cambios.

Para ejecutar el conjunto completo de pruebas, ejecuta:

(.venv) $ tox

(.venv) $ tox

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

La ejecución del conjunto completo de pruebas puede tardar un rato. Puedes acelerarla considerablemente ejecutando tox en paralelo, es decir, ejecutando tox p (o tox run-parallel). Cuando ejecutes el conjunto de pruebas en paralelo, recibirás menos información sobre el progreso de las pruebas mientras se ejecutan, pero al final de la ejecución seguirás obteniendo un resumen de los problemas detectados. Deberías ver algún mensaje que indique que se han ejecutado las pruebas. Es posible que veas pruebas de tipo SKIPPED, pero nunca deberías obtener resultados de pruebas FAIL o ERROR. Ejecutamos nuestro conjunto completo de pruebas antes de fusionar cada parche. Si ese proceso detecta algún problema, no fusionamos el parche. Si encuentras un error o fallo en las pruebas, o bien hay algo extraño en tu entorno de pruebas, o bien has encontrado un caso extremo que no habíamos visto antes; en cualquier caso, ¡háznoslo saber!

Además de las pruebas que se superen, esto debería indicar una cobertura de pruebas del 100%.

Ejecución de variantes de pruebas

Ejecutar pruebas para múltiples versiones de Python

Por defecto, muchos de los comandos de tox intentarán ejecutar el conjunto de pruebas varias veces, una vez por cada versión de Python compatible con BeeWare Docs Tools. Sin embargo, para ello, cada una de las versiones de Python debe estar instalada en tu equipo y estar disponible para el proceso de [detección]tox de Python de (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). En general, si una versión de Python está disponible a través de la ruta en PATH, entonces tox debería poder encontrarla y utilizarla.

Ejecuta solo el conjunto de pruebas

Si estás realizando iteraciones rápidas en una nueva prestación, no es necesario que ejecutes el conjunto completo de pruebas; puedes ejecutar solo las pruebas unitarias. Para ello, ejecuta:

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Ejecutar un subconjunto de pruebas

Por defecto, tox ejecutará todas las pruebas del conjunto de pruebas unitarias. Cuando estés desarrollando una nueva prueba, puede resultarte útil ejecutar solo esa prueba. Para ello, puedes pasar cualquier especificador de pytest como argumento a tox. Estas rutas de pruebas son relativas al directorio briefcase. Por ejemplo, para ejecutar solo las pruebas de un único archivo, escribe:

(.venv) $ tox -e py -- tests/ruta_a_prueba_archivo/prueba_algún_test.py

(.venv) $ tox -e py -- tests/ruta_a_prueba_archivo/prueba_algún_test.py

(.venv) C:\...>tox -e py -- tests/ruta_archivo_test/prueba_algún_testpy

Seguirás obteniendo un informe de cobertura al ejecutar una parte del conjunto de pruebas, pero los resultados de cobertura solo incluirán las líneas de código que se hayan ejecutado en las pruebas concretas que hayas ejecutado.

Ejecuta el conjunto de pruebas para una versión concreta de Python

Por defecto, tox -e py se ejecutará utilizando el intérprete que se identifique como python en tu equipo. Si tienes varias versiones de Python instaladas y deseas probar una versión concreta de entre las que tienes instaladas, puedes especificar la versión de Python que deseas utilizar. Por ejemplo, para ejecutar el conjunto de pruebas en Python 3.10, escribe:

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

Se puede ejecutar un subconjunto de pruebas añadiendo -- y una especificación de prueba a la línea de comandos.

Ejecuta el conjunto de pruebas sin cobertura (rápido)

De forma predeterminada, tox ejecutará el conjunto de pruebas de pytest en modo de un solo subproceso. Puedes acelerar la ejecución del conjunto de pruebas ejecutándolo en paralelo. Este modo no genera archivos de cobertura debido a las dificultades que entraña capturar la cobertura dentro de los procesos generados. Para ejecutar una sola versión de Python en modo «rápido», ejecuta:

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

Se puede ejecutar un subconjunto de pruebas añadiendo -- y una especificación de prueba a la línea de comandos; se puede utilizar una versión específica de Python añadiendo la versión al objetivo de la prueba (por ejemplo, py310-fast para ejecutar fast en Python 3.10).

Cobertura del código

BeeWare Docs Tools mantiene una cobertura de ramas del 100 % en su código fuente. Cuando añadas o modifiques código en el proyecto, debes añadir código de prueba para garantizar la cobertura de cualquier cambio que realices.

Sin embargo, BeeWare Docs Tools está diseñado para múltiples plataformas, así como para múltiples versiones de Python, por lo que no es posible verificar la cobertura completa en una sola plataforma y versión de Python. Para solucionar esto, se definen varias reglas de cobertura condicionales en la sección tool.coverage.coverage_conditional_plugin.rules de pyproject.toml (por ejemplo, no-cover-if-is-windows se puede utilizar para marcar un bloque de código que no se ejecutará al ejecutar el conjunto de pruebas en Windows). Estas reglas se utilizan para identificar secciones de código que solo están cubiertas en plataformas o versiones de Python concretas.

Cabe destacar que la generación de informes de cobertura entre distintas versiones de Python puede presentar algunas peculiaridades. Por ejemplo, si los archivos de cobertura se generan con una versión de Python, pero el informe se elabora con otra, este puede incluir falsos positivos relativos a ramificaciones omitidas. Por este motivo, para generar los informes de cobertura siempre se debe utilizar la versión más antigua de Python empleada para crear los archivos de cobertura.

Interpretación de los resultados de la cobertura

Al final de la salida de la prueba de cobertura debería aparecer un informe con los datos de cobertura recopilados:

Nombre    Estados   Sucursal de referencia   Parte de la sucursal   Cobertura   Falta
 ---------------------------------------------------
 TOTAL    7540 0   1040 0  100,0 %

Esto nos indica que el conjunto de pruebas ha ejecutado todas las ramificaciones posibles del código. Aunque esto no garantiza al 100 % que no haya errores, sí significa que estamos probando cada línea de código del código fuente.

Si realizas cambios en el código, es posible que se produzca una brecha en esta cobertura. Cuando esto ocurra, el informe de cobertura te indicará qué líneas no se están ejecutando. Por ejemplo, supongamos que hemos realizado un cambio en some/interesting_file.py, añadiendo nueva lógica. El informe de cobertura podría tener un aspecto similar al siguiente:

Name                                                                  Stmts   Miss Rama BrPart  Cobertura   Ausencia
 -------------------------------------------------------------------------------
 src/algún/archivo_interesante.py           111      1     26      0  98.1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL                                                                 7540      1   1726      0  99'9%

Esto nos indica que la línea 170, las líneas 302-307 y una ramificación que salta de la línea 320 a la línea 335 no están siendo ejecutadas por el conjunto de pruebas. Tendrás que añadir nuevas pruebas (o modificar una ya existente) para restablecer esta cobertura.

Informe de cobertura para la plataforma de ejecución y la versión de Python

Puedes generar un informe de cobertura para tu plataforma y versión de Python. Por ejemplo, para ejecutar el conjunto de pruebas y generar un informe de cobertura en Python 3.10, ejecuta:

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Informe de cobertura para la plataforma de alojamiento

Si todas las versiones compatibles de Python están disponibles para tox, se puede generar un informe de cobertura para la plataforma de host ejecutando:

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Informes de cobertura en HTML

Se puede generar un informe de cobertura HTML añadiendo -html a cualquiera de los nombres de entorno de cobertura tox, por ejemplo:

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

¡No se trata solo de escribir pruebas!

Aunque nos aseguramos de probar todo nuestro código, la tarea no consiste solo en mantener ese nivel de pruebas. Parte de la tarea consiste en revisar el código sobre la marcha. Se podría escribir un conjunto completo de pruebas para un chaleco salvavidas de hormigón… ¡pero un chaleco salvavidas de hormigón seguiría siendo inútil para el fin al que está destinado!

A medida que desarrolles pruebas, debes comprobar también que el módulo principal sea coherente internamente. Si detectas algún nombre de método que no sea coherente internamente (por ejemplo, algo que se llame on_select en un módulo, pero on_selected en otro), o en el que los datos no se gestionen de forma coherente, márcalo y avísanos creando un ticket. O, si estás seguro de saber qué hay que hacer, crea una solicitud de incorporación de cambios que solucione el problema que has encontrado.

Una vez que todo funcione correctamente, puedes enviar una solicitud de extracción con tus cambios.

Crear documentación

Documentación de la construcción

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

Antes de crear la documentación, configura un entorno de desarrollo.

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 Docs Tools 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 Docs Tools dispone de un modo de «vista previa en directo».

¡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:

(venv) $ tox -e docs-live

(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] Servido en 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.

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:

(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 Docs Tools 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:

(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:

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

Análisis de documentación

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

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

Una vez que hayas creado correctamente los documentos, estarás listo para escribir la documentación.

Redactar documentación

Redacción de documentación

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

Antes de comenzar a escribir la documentación, asegúrate de que puedes crear la documentación y de que estás trabajando en una rama.

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 documentación nueva

Si está añadiendo un documento nuevo, hay unos pocos pasos más relacionados.

Necesitará crear el documento en la ubicación apropiada dentro del directorio docs/es. A modo de ejemplo, diremos que está añadiendo un documento nuevo 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:

- ./ruta/al/directorio/*

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

- [Mi nuevo documento](new_doc.md)

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

Una vez que estés satisfecho con tu nueva documentación, puedes enviar una solicitud de extracción con los cambios propuestos.

Añadir una nota de cambio

Añadir información sobre cambios para las notas de la versión

{{ nombre_formal }} utiliza towncrier para asistir en la construcción de las notas de cada versión. Cuando envíe una solicitud de extracción, debe 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 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 defecto 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 Docs Tools; 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.prestación.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 Docs Tools. 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

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:

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

1 archivo reformateado, 488 archivos dejados sin cambiar

ruff check...............................................................Aprobado
codespell................................................................Aprobado

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

1 archivo reformateado, 488 archivos dejados sin cambiar

ruff check...............................................................Aprobado
codespell................................................................Aprobado

(.venv) C:\...>git add algo/interesante_archivo.py
(.venv) C:\...>git commit -m "Cambio menor"
check toml...............................................................Aprobado
check yaml...............................................................Aprobado
check for case conflicts...........................................Aprobado
check docstring is first.............................................Aprobado
fix end of files............................................................Aprobado
trim trailing whitespace...........................................Aprobado
ruff format.................................................................Aprobado
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Aprobado
codespell................................................................Aprobado

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.

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

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

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Aprobado
check yaml...............................................................Aprobado
check for case conflicts...........................................Aprobado
check docstring is first............................................Aprobado
fix end of files..........................................................Aprobado
trim trailing whitespace..........................................Aprobado
ruff format................................................................Aprobado
ruff check..................................................................Aprobado
codespell...................................................................Aprobado
[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.

(.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/<tu Id de usuario de GitHub>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<tu Id de usuario en GitHub>/BeeWare Docs Tools.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/<tu Id de usuario de GitHub>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<tu Id de usuario en GitHub>/BeeWare Docs Tools.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/<tu id usuario en GitHub>/BeeWare Docs Tools/pull/new/fix-win11-build
remote:
To https://github.com/<tu id usuario en GitHub>/BeeWare Docs Tools.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 la instrucción de CLI GitHub gh pr create --web para abrir un navegador web en la página de creación del RP.

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.

gh pr create

No utilices el comando gh pr create sin más para crear tu solicitud de incorporación de cambios. Los proyectos de BeeWare utilizan una plantilla para las solicitudes de incorporación de cambios, y exigimos que todas las contribuciones sigan esta plantilla. El comando gh pr create evita el uso de esta plantilla.

Contenido de la solicitud de incorporación de cambios

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.

Tu solicitud de incorporación de cambios debe seguir la plantilla de solicitud de incorporación de cambios de BeeWare. Si has creado tu solicitud de incorporación de cambios a través de la interfaz web de GitHub, esta plantilla aparecerá como punto de partida para la descripción de tu solicitud. Si, sin darte cuenta, creas una solicitud de incorporación de cambios sin utilizar esta plantilla, puedes editarla para añadir el contenido de la plantilla; sin embargo, es obligatorio incluir dicho contenido y rellenarlo correctamente.

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.

Las herramientas de IA tienden especialmente a redactar mensajes de solicitud de incorporación de cambios (PR) demasiado extensos y poco útiles. Si utilizas una herramienta de IA para generar tu PR, tú eres responsable de garantizar que la descripción de la solicitud de incorporación de cambios sea concisa y solo contenga información útil para el proceso de revisión. Por ejemplo, no es necesario que incluyas detalles sobre un «protocolo de pruebas» que describa cómo ejecutar el conjunto de pruebas, ni una «justificación» de por qué hay que corregir un error. Los cuerpos de las solicitudes de incorporación de cambios excesivamente prolijos pueden dar lugar a que tu solicitud se cierre sin ser revisada, ya que no respetan los recursos limitados del equipo principal.

La plantilla de solicitud de incorporación de cambios de BeeWare

La plantilla de solicitud de incorporación de cambios de BeeWare no es opcional. Exigimos que todas las solicitudes de incorporación de cambios sigan esta plantilla. Tu solicitud de incorporación de cambios no se revisará si no incluye la sección «Lista de verificación de PR» o si tus respuestas a las preguntas de las casillas de verificación están incompletas o son incoherentes. Si has utilizado una herramienta de IA para generar tu solicitud de incorporación de cambios, debes marcar la casilla correspondiente y proporcionar detalles en la línea «Asistido por:».

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.

Como parte del envío de una solicitud de extracción, deberás incluir una nota de cambio antes de que pueda ser revisada.