Saltar a contenido

Añadir documentación

Puede que tenga el mejor software del mundo, pero si nadie sabe cómo utilizarlo, ¿de qué sirve? La documentación siempre puede mejorarse, ¡y necesitamos tu ayuda!

Formularios de documentación

La documentación de {{ nombre_formal }} está escrita usando MkDocs y Markdown. Nuestro objetivo es seguir el marco Diataxis para estructurar la documentación.

El marco de Diataxis describe cuatro "formas" de documentación:

  • Tutorial - Una experiencia de aprendizaje guiada, con un punto final de proyecto específico.
  • Guía práctica - Instrucciones que guían al lector hacia un objetivo o resultado específico.
  • Guía temática - Discusión de una sola idea, explicada de forma que los conceptos subyacentes queden claros.
  • Referencia - Descripciones técnicas de API específicas u otras interfaces.

Antes de iniciar cualquier contribución a la documentación, es importante identificar qué forma es la más adecuada. Muchas propuestas de documentación se describirán inicialmente como una solicitud de "un tutorial sobre X", pero en la mayoría de los casos, lo que realmente se necesita es información sobre cómo hacerlo, una guía temática o una referencia mejorada.

Como ejemplo, considere la tarea de escribir documentación sobre cómo hornear galletas.

Tutorial

Un tutorial es una introducción, sobre todo dirigida a principiantes, cuyo objetivo debe ser llevar al lector desde un punto de partida limpio hasta un producto acabado. Requiere instrucciones muy específicas y explicaciones detalladas que contextualicen los pasos del tutorial. No debes asumir nada sobre la experiencia del lector con la herramienta que se está explicando, aunque es razonable asumir algún conocimiento básico de Python.

El tutorial debe contener puntos de control periódicos en los que el lector pueda comprobar que ha conseguido hacer lo que se ha descrito. En cada punto de control, los criterios de éxito deben estar claros. Los casos de fallo conocidos deben describirse con claridad, incluyendo explicaciones de los posibles errores o problemas que pueda experimentar el lector. Deben señalarse las cosas que cambian como resultado de las acciones que ha llevado a cabo el lector, aunque parezcan obvias. Se recomienda la repetición, sobre todo si se trata de establecer una práctica recomendada o procesos comunes. Hay que evitar las explicaciones internas, así como los caminos alternativos para llegar al mismo resultado.

Un tutorial sobre cómo hornear galletas es algo más que una receta. Las instrucciones de un tutorial deben ser accesibles para alguien que nunca haya horneado antes (por ejemplo, un niño), y tendrían que dar cuenta de cosas que un panadero experimentado daría por sentadas, como la forma de cremar el azúcar y la mantequilla, el proceso de precalentamiento del horno o cuánto tiempo deben dejarse enfriar las galletas antes de comerlas. El objetivo del tutorial no es producir una galleta, sino transmitir los fundamentos de la repostería. La galleta resultante es el sabroso manjar que convence a alguien para emprender el tutorial en primer lugar.

Guía práctica

Una guía práctica debe centrarse en un caso concreto de uso en el mundo real y en resultados prácticos, más que en explicaciones teóricas. A diferencia de un tutorial, puede presuponer cierta familiaridad con las herramientas existentes. El lector debe ser capaz de seguir la guía de principio a fin y alcanzar el objetivo, pero para ello puede necesitar algunos conocimientos previos. Debe incluir una serie de instrucciones concretas o pasos lógicos que deben seguirse para alcanzar el objetivo de la guía.

Una receta de un libro de cocina es un buen ejemplo de guía práctica. Hay muchas recetas de galletas con pepitas de chocolate, y todas tienen características comunes, pero cualquier receta específica debe poder seguirse de principio a fin y dar un resultado uniforme. Una buena receta de galletas de chocolate no se extenderá en las ventajas relativas de los distintos tipos de azúcar o harina, ni dará instrucciones detalladas sobre técnicas o procesos básicos; sólo incluirá los ingredientes y las instrucciones para hornear una tanda de galletas, dando por sentado que el lector está familiarizado con la repostería.

Guía temática

Una guía temática describe un único tema o idea. Puede incluir ejemplos de código o instrucciones, pero se centra mucho más en ofrecer una imagen de alto nivel de un concepto general. Puede incluir opiniones y perspectivas alternativas, pero debe mantenerse el enfoque en el tema específico de la guía.

Una guía temática sobre la elaboración de galletas podría ahondar en la historia de las galletas como producto horneado, explorar la forma en que los procesos industrializados dan lugar a diferentes tipos de galletas en comparación con las galletas caseras, o sugerir formas en que las galletas pueden incorporarse a una dieta equilibrada. Por sí mismo, no sería un documento muy útil si se quisiera hornear una galleta, pero podría proporcionar los antecedentes que permitirían a alguien familiarizado con la panadería personalizar con éxito una receta de galletas existente.

Referencia

La documentación de referencia está orientada a la información y describe aspectos concretos del funcionamiento de una biblioteca de herramientas. A menudo puede generarse a partir del propio código, pero una buena documentación de la API puede requerir más explicaciones y contexto. Aunque a veces puede incluir ejemplos de uso, deben evitarse las explicaciones detalladas.

Una guía de referencia sobre repostería podría describir los tipos de azúcar que pueden utilizarse y detallar sus propiedades cuando se emplean en repostería. Describiría hechos literales sobre el azúcar, pero un debate más amplio sobre la elección entre tipos de azúcar debería ser objeto de una guía práctica o temática. La información nutricional que se encuentra en la mayoría de los alimentos envasados se consideraría documentación de referencia.

Estilo de documentación

La documentación de {{ nombre_formal }} sigue las directrices descritas en la guía de estilo de la documentación. Esta guía incluye el estilo y el formato básicos, y el proceso para la corrección ortográfica. También cubre varios detalles de sintaxis Markdown, como la sintaxis de enlaces de referencia, consejos para trabajar con bloques de código y manejo de imágenes.

Contribución a la documentación

Propuesta de nueva documentación

Así que tienes una idea sobre una mejora para BeeWare - ¿cómo presentar esa idea para su consideración?

Investigue

El primer paso es buscar en el gestor de incidencias BeeWare los [feature issues (issues tagged "enhancement")] existentes (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Aenhancement&type=issues), problemas de documentación (problemas etiquetados como "documentación"), o Hilos de discusión para ver si la idea ya se ha sugerido antes. Si es así, y usted tiene un nuevo contexto o ideas que añadir, inclúyalas en el hilo existente. Si necesitas ayuda con tu investigación, puedes preguntar en el canal #dev del BeeWare Discord. Es posible que podamos indicarte hilos ya existentes, proporcionarte un contexto que quizá no conozcas o relacionar tu idea con otra que no parezca inmediatamente relacionada.

Debatir la idea

Si no encuentra ninguna referencia a su idea, inicie un Hilo de debate. Describa a grandes rasgos la finalidad y el caso de uso de su idea. Incluya cualquier idea que tenga sobre el aspecto que tendría la función, si se implementara, como la forma general de una API, el aspecto visual de una capacidad o el documento que se añadiría. Si procede, también debes incluir cualquier investigación que hayas realizado sobre cómo se manifestaría tu idea en diferentes plataformas.

Una vez abierto el hilo de debate, el equipo de BeeWare y el resto de la comunidad responderán. El equipo central intentará ofrecer al menos una primera impresión de su idea en un plazo de dos días laborables. Si una idea es especialmente compleja, un análisis más detallado puede llevar hasta una semana. Acontecimientos como vacaciones y conferencias pueden alargar ligeramente estos plazos.

Esta es su oportunidad de participar en una conversación sobre su idea. Podemos pedirle más detalles o contexto. Otros miembros de la comunidad también pueden participar en el debate, aportando otras perspectivas, sugerencias o contrapropuestas. El resultado de este debate determinará los siguientes pasos.

Es importante entender que no todas las ideas serán aceptadas. La razón por la que este proceso comienza con una propuesta es para evitar que usted haga todo el trabajo y luego descubra que hay una razón por la que su cambio no será aceptado.

Esto no significa que no fuera una buena idea. Puede haber razones técnicas por las que no pueda llevarse a cabo. Por ejemplo, podríamos rechazar una idea si:

  • Sería difícil o imposible aplicarlo de forma fiable en todas las plataformas compatibles.
  • Sería difícil de mantener, o su mantenimiento requeriría el acceso a tecnología o programas informáticos que no están ampliamente disponibles; o
  • Sirve a un público nicho, pero impone una sobrecarga significativa a otros usuarios.

Si determinamos que tu idea no encaja, no significa necesariamente que debas renunciar a ella. Si bien podemos rechazar una idea específica, podemos estar mucho más dispuestos a añadir una interfaz de plugin u otro punto de extensión que le permita mantener la misma característica como una biblioteca externa. De este modo, podrá disponer de la función, pero sin que los problemas específicos de mantenimiento o las limitaciones de la función se conviertan en una restricción para el propio proyecto.

Convertir en una solicitud formal

Una vez que la discusión ha llegado a un consenso sobre la forma de una característica, puede crear una nueva feature request issue, en el issue tracker BeeWare, que resuma la discusión, enlazando a la discusión para el contexto.

No tienes por qué implementar tú mismo tu propuesta de funcionalidad; puedes abrir una incidencia con los detalles de lo que propones. Sin embargo, el mero hecho de publicar la incidencia no significa que vaya a implementarse. Tendrás que esperar a que otra persona interesada en la misma función, ya sea otro miembro de la comunidad o el equipo central, la recoja; sin embargo, no está garantizado que esto ocurra. Si quieres la implementación garantizada, tendrás que implementarla tú mismo, o pagar a alguien para que lo haga por ti.

Configurar un entorno de desarrollo

Contribuir a BeeWare 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 (como venv).

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

$ python3 --version

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

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

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

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

$ python3 --version

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

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

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

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

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

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

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

Configure su entorno de desarrollo

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

Clonar el repositorio BeeWare

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

Fork el repositorio BeeWare, y luego:

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

(sustituyendo tu nombre de usuario de GitHub)

Fork el repositorio BeeWare, y luego:

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

(sustituyendo tu nombre de usuario de GitHub)

Fork el repositorio BeeWare, y luego:

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

(sustituyendo tu nombre de usuario de GitHub)

Crear un entorno virtual

Para configurar un entorno virtual y actualizar pip, ejecute:

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

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

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

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

Instalar BeeWare

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

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

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

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

Activar precommit

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

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

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

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

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

Trabajar desde una sucursal

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

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

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

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

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

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

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

(.venv) C:\...>git switch -c fix-win11-build
Evitar la desviación del alcance

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

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

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

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

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

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

Documentación de la construcción

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

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

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

Vista previa de la documentación en directo

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

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

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

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

Para iniciar el servidor en vivo:

(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] Serving on http://127.0.0.1:8000/

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

docs-live es un primer paso

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

Construcción local

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

Generación de una compilación local

Para generar una compilación local:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

Generación de una compilación local traducida

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

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

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

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

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

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

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

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

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

Documentación

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

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

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

Esto validará la documentación no contiene:

  • hipervínculos muertos
  • palabras mal escritas

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

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

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

Actualización de la documentación existente

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

Añadir nueva documentación

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

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

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

- ./path/to/directory/*

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

- [My new document](new_doc.md)

Redactar la documentación

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

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

Añadir una nota de cambio

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

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

Existen cinco tipos de fragmentos:

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

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

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

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

La nota de cambio correspondiente diría algo así

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

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

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

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

Enviar una solicitud de extracción

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

Trabajar con precommit

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

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

1 file reformatted, 488 files left unchanged

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

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

1 file reformatted, 488 files left unchanged

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

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

1 file reformatted, 488 files left unchanged

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

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

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

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

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

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

Sube tus cambios a GitHub y crea tu pull request

La primera vez que hagas un push a GitHub, se te proporcionará una URL que te llevará directamente a la página de GitHub para crear un nuevo pull request. Sigue la URL y crea tu pull request.

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

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

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

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

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

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

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

La CLI de GitHub: gh

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

Contenido de la solicitud de extracción

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

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

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

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

1234` en la descripción de su pull request. Esto hará que el problema se cierre

automáticamente cuando se fusione la pull request. Puede hacer referencia a otras discusiones, incidencias o pull requests utilizando la misma sintaxis #1234. Puede hacer referencia a una incidencia en un repositorio diferente anteponiendo el número - por ejemplo python/cpython#1234 haría referencia a la incidencia 1234 en el repositorio CPython.

Integración continua

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

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

Cuando CI falla, los enlaces de fallo aparecerán en la parte inferior de la página PR, bajo el título "Algunas comprobaciones no tuvieron éxito". Verá una lista de comprobaciones fallidas, que aparecerá en la parte superior de la lista de todas las comprobaciones si también hay comprobaciones correctas. Si hace clic en el enlace del fallo, accederá al registro. El registro suele proporcionar toda la información necesaria para averiguar la causa del fallo. Lea el registro e intente averiguar por qué se produce el fallo y, a continuación, haga lo necesario para resolverlo.

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

Para desencadenar una nueva ejecución de CI, debe enviar nuevos cambios a su rama.

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

Las comprobaciones pre-commit y towncrier.

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

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

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