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

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.