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 BeeWare está escrita usando MkDocs y Markdown. Nuestro propósito 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 novatos, 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 prestaciones 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 e 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 del 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.

Contribuir en la documentación

Propuesta de documentación nueva

Por tanto ya tienes una idea sobre una mejora para BeeWare: ¿cómo presentar esa idea a que sea para consideración?

Haz tu investigación

El primer paso es buscar el seguimiento de la incidencia BeeWare para la prestación de incidencias (incidencias etiquetadas "enhancement"), incidencias de documentación (incidencias etiquetadas "documentation"), o Hilos de discusión para ver si ka idea ha sido sugerida antes. Si tiene, y tiene contexto o ideas nuevas o para añadir, inclúyelas en el hilo existente. Si le gustaría asistir con su investigación, puede solicitar en el canal #dev en el Discord de BeeWare. Es posible que podamos orientarte hacia hilos de conversación existentes, proporcionarte un contexto que quizás desconozcas o conectar tu idea con otra que, a primera vista, no parezca estar 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 tendría sobre como aparecería la prestación, si se implementara, tal como la forma general de un API, el aspecto visual de una capacidad o el documento que se añadiría. Si es aplicable, también incluiría cualquier investigación que hayas realizado sobre como se manifestaría tu idea en plataformas diferentes.

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 contra‐propuestas. El resultado de este debate determinará los siguientes pasos.

Es importante entender que no serán aceptadas todas las ideas. La razón por la que este proceso comienza con una propuesta es para evitar que hagas todo el trabajo y luego descubras 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 implementar de forma fiable a través de todas las plataformas admitidas; o
  • Sería difícil de mantener, o su mantenimiento requeriría acceder a tecnología o software que no estén ampliamente disponibles; o
  • Sirve a un nicho público, pero impone una sobrecarga significativa a otros usuarios.

Si determinamos que tu idea no encaja, no significa necesariamente que debas renunciarla. 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 prestación como una biblioteca externa. De este modo, podrá disponer de la prestación, pero sin que los problemas específicos de mantenimiento o las limitaciones de la prestación se conviertan en una restricción para el propio proyecto.

Convertir en una requerimiento formal de prestación

Una vez que la discusión ha llegado a un consenso sobre la forma de una prestación, puede crear una nueva prestación solicitada de incidencia, en la incidencia del seguimiento BeeWare, que resuma la discusión, enlazando a la discusión para el contexto.

No tienes por qué implementar tú mismo tu propuesta de prestación; 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 prestación, ya sea otro miembro de la comunidad o el equipo central, la recoja; sin embargo, no está garantizado que esto suceda. 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 (tal como venv).

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

$ python3 --version

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

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

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

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

$ python3 --version

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

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

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

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

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

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

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

Configura tu entorno de desarrollo

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

Clonar el repositorio BeeWare

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

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Bifurca el repositorio BeeWare, y luego:

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

(sustituir tu identificador de GitHub)

Establecer un repositorio ascendente

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

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

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

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

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

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

$ git push --tags

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

Crea un entorno virtual

Para configurar un entorno virtual y subir la versión de pip, ejecute:

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

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

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

Tu solicitud ahora tendría un prefijo (.venv) delante.

Instalar BeeWare

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

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

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

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

Activar pre‐commit

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

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

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

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

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

Trabajar desde una sucursal

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

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

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

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

Para crear una rama de prestaciones fix-win11-build, ejecute:

(.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 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? ¿Podría implementarse una prestación con una limitación o defecto conocidos, y arreglar 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.

Documentación de construcción

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

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

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

Vista previa en directo de la documentación

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

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

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

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

Ejecuta docs-live para funcionar con el servidor en directo está pensado para la iteración inicial. Tú debes ejecutar siempre una compilación local antes de enviar un pull request.

Construcción local

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

Generar de una compilación local

Para generar una compilación local:

(venv) $ tox -e docs

(venv) $ tox -e docs

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

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

Generar una compilación local traducida

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

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

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

Documentación

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

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

///

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 asistir en la construir las notas de cada versión. Cuando envíe un pull request a una de las herramientas aplicables, necesitará incluir una nota de cambio — esta nota de cambio se convertirá en el apunte de las notas de la versión que describe el cambio que se ha realizado.

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

Hay cinco tipos de fragmentos:

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

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

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

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

La nota de cambio correspondiente leería algo así como:

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

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

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

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

Enviar una solicitud de extracción

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

Trabajar con pre-confirmación

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

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

1 file reformatted, 488 files left unchanged

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

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

1 file reformatted, 488 files left unchanged

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

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

1 file reformatted, 488 files left unchanged

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

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

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

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

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

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

Sube tus cambios a GitHub y crea tu solicitud de extracción

La primera vez que hagas una extracción (push) a GitHub, se te proporcionará una URL que te llevará directamente a la página de GitHub para crear una solicitud de extracción nueva. Sigue la URL y crea tu «pull request».

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

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

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

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

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

  • Navegue hasta el repositorio upstream, pulse en "Pull Requests" seguido de "New pull request", y elija el desde el que desea enviar su pull request.
  • Si has extraído recientemente, navega al repositorio en desarrollo, localiza la pancarta por encima del listado de archivos que indican que el repositorio ha «tenido recientes extracciones», y pulsa el botón «Comparar y solicitar extracción».
  • Utiliza el comando gh pr create de la CLI de GitHub, y rellena las solicitudes.
  • Utiliza la instrucción de CLI GitHub gh pr create --web para abrir un navegador web en la página de creación del RP.

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

La CLI de GitHub: gh

GitHub proporciona la CLI de GitHub, la cual te da acceso a muchas de las prestaciones de GitHub desde tu terminal, a través de la instrucción gh. La documentación de CLI GitHub cubre todas las prestaciones.

Contenido de solicitud de extracción

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

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

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

Si su pull request va a resolver la incidencia #1234, debe incluir el texto Fixes #1234 en la descripción de su pull request. Esto hará que la incidencia se cierre automáticamente cuando se fusione la pull request. Puede hacer referencia a otras discusiones, incidencias o pull requests utilizando la misma sintaxis #1234. Puede hacer referencia a una incidencia en un repositorio diferente anteponiendo el número; por ejemplo python/cpython#1234 haría referencia a la incidencia 1234 en el repositorio CPython.

Integración continua

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

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

Cuando IC falla, los enlaces de fallo aparecerán en la parte inferior de la página RP, bajo el título «Algunas comprobaciones no se lograron». Verá una lista de comprobaciones incorrectas, que aparecerá en la parte superior de la lista de todas las comprobaciones si también hay comprobaciones correctas. Si pulsa sobre el enlace del fallo, accederá a la bitácora. La bitácora suele proporcionar toda la información necesaria para averiguar la causa del fallo. Lea por todas las bitácoras e intente averiguar por qué se produce el fallo y, a continuación, haga lo necesario para resolverlo.

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

Para desencadenar una ejecución nueva de IC, debe subir los cambios nuevos a su rama.

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

Las comprobaciones pre-commit y towncrier

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

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

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