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

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.