Notas de release de GitHub: genéralas y hazlas legibles
7 min de lectura
Las notas de release de GitHub son la descripción adjunta a un release en la página Releases del repositorio, y GitHub puede escribir un primer borrador por ti a partir de los pull requests fusionados desde la etiqueta anterior. El borrador es una lista de títulos de pull requests agrupados por etiqueta, con una línea de colaboradores y un enlace de comparación. Es exacto, completo y está escrito para las personas que fusionaron los pull requests. Convertirlo en algo que un usuario del proyecto pueda leer requiere un archivo .github/release.yml y una pasada breve de edición, y ambos se describen abajo.
| Forma de producir las notas | Dónde se ejecuta | Qué obtienes |
|---|---|---|
| Botón “Generate release notes” | Formulario de release en la interfaz web | Títulos de PR desde la última etiqueta, agrupados por las categorías de release.yml |
gh release create v1.4.0 --generate-notes | GitHub CLI, en local o en CI | El mismo borrador, creado junto con el release en un solo comando |
POST /repos/{owner}/{repo}/releases/generate-notes | API REST | El borrador como texto, sin crear un release, para tu propio pipeline |
| release-please, semantic-release, conventional-changelog | GitHub Actions o un job de release | Notas a partir de los mensajes de commit en lugar de los títulos de PR, más saltos de versión y un CHANGELOG.md |
| Escritas a mano | El formulario de release | Lo que escribas, sin enlace de vuelta a los pull requests |
¿Cómo se generan automáticamente notas de release en GitHub?
Abre el formulario de release, elige o crea la etiqueta y pulsa “Generate release notes”. GitHub localiza la etiqueta del release anterior, lista cada pull request fusionado en la rama de destino entre las dos y escribe una línea por pull request con su título, autor y número. Desde la línea de comandos, gh release create <tag> --generate-notes hace lo mismo y publica el release en un solo paso; --notes-start-tag cambia desde qué etiqueta anterior empieza el rango.
La función trabaja a partir de pull requests, así que un repositorio que fusiona directamente en main sin pull requests obtiene un borrador vacío. Los squash merges no dan problema, porque el pull request sigue existiendo. Los merge commits de una rama de larga vida hacia main producen una línea para el pull request que fusiona, sin ninguno de los pull requests que se fusionaron antes en esa rama. Si el rango parece incorrecto, la causa habitual es una etiqueta anterior ausente o mal ordenada; el generador usa el último release de la rama de destino, y una etiqueta sin release asociado se ignora.
La página de GitHub Docs sobre notas de release generadas automáticamente cubre el botón, y el manual de gh release create cubre los flags de la CLI.
¿Qué cambia release.yml?
.github/release.yml le dice al generador qué pull requests dejar fuera y cómo agrupar el resto. Sin él, todos los pull requests acaban en una sola lista, Dependabot incluido. Con él, los pull requests se ordenan en categorías por etiqueta, y el ruido etiquetado o escrito por bots desaparece.
# .github/release.yml
changelog:
exclude:
labels:
- skip-changelog
authors:
- dependabot
- renovate
categories:
- title: Breaking changes
labels:
- breaking-change
- title: New
labels:
- enhancement
- title: Fixed
labels:
- bug
- title: Other changes
labels:
- "*"Tres reglas que conviene conocer. Las categorías se evalúan en orden, así que un pull request con breaking-change y bug a la vez va bajo el primer encabezado que coincida. El comodín "*" es obligatorio si quieres que los pull requests sin etiqueta aparezcan; sin él se descartan en silencio. Y el archivo solo afecta a lo que el generador escribe, de modo que cambiarlo no toca las notas que ya existen. Los equipos que ya etiquetan pull requests para exigir una entrada de changelog en CI pueden reutilizar aquí las mismas etiquetas.
¿Por qué se leen mal las notas de release generadas por GitHub?
Porque el título de un pull request se escribe para quien lo revisa, antes de que el cambio esté terminado, y describe el código. “Refactor export worker to use streaming” es un buen título de pull request y una nota de release inútil, porque quien lee el release quiere saber que las exportaciones de más de 100 MB ya no agotan el tiempo de espera.
La segunda razón es que cada pull request fusionado pesa lo mismo. Una corrección de una errata de una línea queda junto a un flujo de autenticación nuevo, en el orden en que se fusionaron. El lector tiene que recorrer la lista entera para encontrar las tres líneas que le afectan.
La tercera es que el borrador no tiene apertura. Una lista de cuarenta líneas sin una frase encima no le dice a nadie si este release es seguro de adoptar, necesita una migración o existe solo para fijar una dependencia.
¿Qué debería cambiar la pasada de edición?
Conserva la lista generada y añade sobre ella, en lugar de reescribir desde cero. La lista es la pista de auditoría; los números de pull request son la forma en que alguien rastrea una línea hasta el diff. La pasada de edición añade las partes que el generador no puede conocer.
- Escribe dos o tres frases arriba. Para qué sirve este release, si actualizar exige alguna acción y qué leer primero. Si hay un cambio que rompe algo, dilo en la primera línea.
- Reescribe las líneas que importan al lector desde su lado: el síntoma que desapareció, lo que ahora puede hacer, el ajuste que cambió de sitio. Deja el número del pull request al final de la línea. Cómo escribir notas de versión tiene la forma completa; notas de versión de corrección de errores cubre en concreto las líneas de correcciones.
- Mueve a su propia sección todo lo que el lector tenga que hacer, con el comando o el ajuste exacto. Un cambio que rompe algo enterrado en la lista de “Other changes” es un ticket de soporte dentro de una semana.
- No borres nada de la lista generada. Pliégala bajo un encabezado “Lista completa de cambios” si es larga, pero consérvala, porque los propios colaboradores del proyecto la usan.
Hecho así, editar las notas de release de GitHub lleva unos diez minutos en un release típico, y las notas sirven a los dos públicos: el resumen de arriba para los usuarios, la lista de abajo para los colaboradores.
¿Debería el release de GitHub ser tu changelog?
Solo si todas las personas que necesitan enterarse de un cambio ya leen la página Releases. Para una librería que los desarrolladores consumen a través de un gestor de paquetes, eso suele ser cierto, y con la página Releases más un CHANGELOG.md en el repositorio basta. Para un producto con usuarios que nunca abren GitHub, no: la página de release está escrita al nivel equivocado, vive detrás de una URL orientada a desarrolladores y nadie sin cuenta de GitHub puede suscribirse a ella.
El patrón que aguanta es tratar el release de GitHub como el registro para desarrolladores y el changelog del producto como el registro para lectores, con el release enlazando a la entrada del changelog. Tags de git, releases y tu changelog explica cómo encajan los tres registros. Si el changelog del producto se genera a partir de los mismos commits, un generador de changelog te da un borrador también para ese lado, y la división de changelog vs. notas de versión explica qué detalle va en cada sitio.
¿Cómo se versionan las propias notas de release?
Un release publicado en GitHub se puede editar en cualquier momento, y la edición no deja historial visible en la página. Para la mayoría de los proyectos eso está bien. Para los proyectos donde las notas son un registro del que dependen clientes o cumplimiento normativo, ayudan dos hábitos: mantener el texto canónico en el repositorio (el CHANGELOG.md, o una carpeta docs/releases/) y hacer que el cuerpo del release apunte a él, y activar los releases inmutables en el repositorio si tu plan lo ofrece, lo que bloquea la etiqueta y los archivos adjuntos una vez publicados. La documentación de GitHub sobre gestión de releases describe los borradores, los pre-releases y la etiqueta “latest”, que se asigna por orden de versión semántica salvo que la fijes a mano.
FAQ
¿Se pueden generar automáticamente las notas de release de GitHub?
Sí. El botón “Generate release notes” del formulario de release, el flag --generate-notes de gh release create y el endpoint REST generate-notes producen un borrador a partir de los pull requests fusionados desde la etiqueta del release anterior. Un archivo .github/release.yml controla la agrupación y las exclusiones.
¿Por qué mis notas de release generadas están vacías? El generador lista pull requests, así que los commits directos a la rama no aparecen, y el rango empieza en el último release de la rama de destino, no en la última etiqueta. Comprueba que el release anterior existe y que los cambios entraron mediante pull requests.
¿Se aplica release.yml a los releases que ya existen? No. Solo da forma a las notas generadas después de que el archivo esté en su sitio. Los cuerpos de los releases existentes se quedan como estaban hasta que alguien los edite.
¿Debería usar las notas de release de GitHub o un CHANGELOG.md? Ambos, si el proyecto tiene colaboradores y usuarios. La página de release es donde miran los desarrolladores y donde viven los archivos adjuntos; el archivo del repositorio sobrevive a una mudanza fuera de GitHub y se puede leer sin conexión. Genera las notas de release, mantén el archivo al día y enlaza uno con el otro.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.