Automatización de changelog, y sus límites

La automatización de changelog funciona cuando automatiza la recolección, la clasificación y la publicación, y se detiene en la selección y la redacción. Automatiza todo y publicas un git log formateado; no automatices nada y el changelog se escribe a ráfagas, de memoria, antes de los lanzamientos. La pregunta útil es qué partes automatizar, no cuánto.

Los proyectos de automatización de changelog fallan en una de dos direcciones, y ambas son predecibles desde la primera reunión de diseño. Automatiza demasiado poco y el changelog es un documento que se supone que alguien actualiza, lo que significa que se actualiza a ráfagas, por quien saque la pajita más corta. Automatiza demasiado y se convierte en un git log formateado: completo, preciso, y que no lee nadie.

¿Qué partes de un changelog deberían automatizarse?

Tres de los cuatro pasos. Recolección y publicación por completo; clasificación como primera pasada con anulación humana; selección y redacción nunca.

Recolección. Sacar los cambios del lugar donde ocurren (commits, PRs, tickets) y ponerlos en una lista. Automatiza esto por completo. Los humanos son malos en ello, es tedioso, y es el paso que se salta bajo plazo. Conventional commits o las etiquetas de PR son la materia prima habitual.

Clasificación. Decidir si algo es Added, Fixed, Changed, Deprecated, Removed o Security. Automatiza la primera pasada a partir del tipo de commit o la etiqueta de PR, y deja que un humano anule. La precisión aquí ronda el ochenta por ciento solo con metadatos, y el veinte por ciento erróneo se concentra justo en las entradas que importan, porque la ambigüedad correlaciona con la importancia.

Selección y redacción. Decidir qué debería saber un lector y cómo decirlo. No automatices esto. Es todo el valor del artefacto. Todo lo demás es logística.

Publicación. Llevar las entradas terminadas a una página, un feed, un correo, un widget en la app, un canal de Slack. Automatiza por completo, y desde una fuente. Aquí es donde va la mayor parte del esfuerzo manual real, y casi nadie lo cuenta. También es el paso que puede decirle a quien pidió el cambio que se lanzó, que es todo el tema de cerrar el ciclo de feedback desde el changelog. La mitad de correo de ese paso tiene su propia forma, en la plantilla de email de novedades.

Ese último punto merece pensarse. Los equipos tienden a ver el changelog como un problema de escritura, y luego pasan la mayor parte del tiempo en distribución: copiar entradas a una herramienta de correo, reformatear para la app, pegar en Slack, actualizar una página de docs. La escritura toma una hora. La copia toma una hora cada lanzamiento, para siempre, y es la parte que debería tener una máquina.

¿Qué pasa cuando se mueve la línea?

Muévela hacia arriba y obtienes un volcado de git. La automatización total desde commits produce bump deps, fix flaky test, wip y address review comments delante de los clientes. Todo equipo que ha hecho esto luego ha añadido un filtro, y el filtro es un paso de selección reintroducido bajo otro nombre, con peor ergonomía.

Muévela hacia abajo y obtienes ráfagas. La recolección totalmente manual significa que las entradas se escriben de memoria en el momento del lanzamiento. Ese es el modo contra el que Keep a Changelog advierte desde el principio, y se degrada en silencio: el changelog parece mantenido hasta la semana en que nadie tuvo tiempo.

¿Cómo es una canalización de automatización de changelog?

Cuatro pasos, con exactamente una puerta humana, colocada donde un borrador se vuelve público.

1. Al mergear, deriva una entrada borrador del PR: tipo a partir de etiqueta o prefijo de commit, título como primer borrador, enlace de vuelta al PR, autora registrada. Colócala en un cajón sin lanzar.
2. Cualquiera puede editar cualquier borrador en cualquier momento, y editar es barato. La mayoría recibe una línea reescrita.
3. Cortar un lanzamiento exige que cada entrada del cajón esté editada o marcada explícitamente como interna. Esta puerta es todo el diseño. Sin ella, los borradores se lanzan sin editar la semana ajetreada.
4. Publicar es un fan-out desde el conjunto lanzado: la página pública, el feed, el correo, el widget, el post de Slack. Una fuente, varias representaciones, sin copiar.

El paso 3 es el único lugar donde se requiere una persona, y toma unos diez minutos por lanzamiento una vez que los borradores son decentes. Cuando hay una petición de cliente involucrada, el borrador también lleva el issue que cierra, que es lo que permite que el paso 4 le avise a quien pidió; la plantilla de solicitud de función está diseñada para que ese enlace sobreviva. Dónde encaja este paso en el flujo de release más amplio es el tema del proceso de gestión de releases.

¿Qué exige la automatización de tus datos?

Nada de lo anterior funciona si el changelog es un archivo Markdown, porque un archivo no se puede renderizar en cinco superficies sin volver a parsearlo, y parsear prosa es cómo terminas con un widget que muestra medio encabezado.

Las entradas necesitan ser estructuradas: un tipo, una fecha, una versión o identificador de lanzamiento, una audiencia, un cuerpo y un enlace. Entonces el archivo, la página, el feed y el correo son todos vistas. Ese punto estructural es lo único que vale la pena hacer bien antes de elegir una herramienta, porque es lo que no puedes añadir después barato. Nada de eso funciona si no se crea de verdad una entrada para cada cambio que la necesita; exigir una entrada de changelog en CI cubre cómo hacer que la pipeline rechace un merge sin entrada, en vez de dejar ese paso a la memoria.

Construimos changeloop, donde el changelog es primero un feed y luego una página, así que lee esto como un interés más que como una recomendación imparcial; los precios son un repositorio gratis sin tarjeta, suficiente para ver la forma. Herramientas de changelog es nuestra recopilación de lo que más hay, incluidos los productos con los que competimos, y el generador de changelog hace los pasos de recolección y clasificación en el navegador si quieres ver la derivación antes de comprometerte con una canalización.

La prueba

Cuenta los minutos entre que un cambio se mergea y ese cambio es visible para una clienta que no lee tu repo. Si la mayoría de esos minutos son alguien copiando texto entre herramientas, la automatización que necesitas está en la publicación, no en la escritura.

FAQ

¿Puede la IA escribir el changelog? Puede redactar uno. Un modelo al que se le da el pull request mergeado produce la mayoría de las veces un primer borrador utilizable del título y el cuerpo, lo cual es la recolección y la clasificación hechas mejor. La selección, si a un lector se le debería decir algo, y la redacción final, siguen necesitando a la persona que conoce a la audiencia, y una canalización que publica borradores sin esa puerta ha automatizado el paso equivocado.

¿Cuál es la diferencia entre un generador de changelog y la automatización de changelog? Un generador convierte commits en una lista formateada una vez, bajo demanda. La automatización se ejecuta en cada merge, mantiene un cajón sin lanzar, condiciona el lanzamiento a revisión humana, y publica en cada superficie desde una fuente. El generador es el primer paso de la canalización, ejecutado a mano.

¿Debería el changelog automatizarse desde commits o desde pull requests? Desde pull requests, donde la unidad de cambio es el PR: el título y la descripción se escriben una vez, para todo el cambio, y el PR enlaza el issue que cierra. La derivación basada en commits funciona cuando el commit es la unidad y sigue una convención.

¿Cómo se evita que la automatización publique cambios internos? Clasifica chore, ci, test, refactor y actualizaciones de dependencias como internos por defecto, y haz que promover a público sea un acto deliberado. El valor por defecto inverso, público a menos que alguien lo oculte, es cómo bump deps llega a los clientes.

Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.

Relacionado en changeloop: Herramientas de changelog comparadas, Generador de changelog