Quién escribe el changelog, y quién debería

Pregúntale a un equipo quién escribe el changelog y la respuesta honesta suele ser “quien se acuerde”, que es el mismo modo de fallo que exigir una entrada de changelog en CI existe para arreglar a nivel mecánico. Pero forzar que una entrada exista no decide quién está cualificada para escribir una buena, y los equipos que se saltan esa pregunta tienden a recurrir por defecto a quien sea más fácil de obligar, normalmente quien abrió el PR, sin comprobar si esa es realmente la persona que puede escribirla bien.

¿Por qué quien abre el PR no es automáticamente quien mejor escribe el changelog?

Porque conoce la implementación, no necesariamente el impacto, y son dos tipos de conocimiento distintos. Dónde se detienen los conventional commits cubre esta brecha desde el lado del mensaje de commit: fix(auth): reject expired refresh tokens es correcto e inútil para una clienta, y quien escribió ese arreglo suele ser la persona menos preparada para traducirlo, porque ha estado pensando en términos del bug durante horas y ha perdido la vista externa de lo que una usuaria realmente experimentó. Esta es la misma razón por la que existen las escritoras técnicas como profesión: traducir la implementación en impacto es una habilidad distinta de haber construido la cosa, y requiere práctica sin importar lo buena que sea la desarrolladora en el propio código.

¿Eso significa que producto o soporte deberían escribir cada entrada en su lugar?

No, porque tienen la brecha opuesta: saben qué le importa a las usuarias pero no siempre qué se lanzó realmente, lo que produce entradas legibles pero ocasionalmente equivocadas en alcance, una afirmación de “ahora soporta X” para una función que sigue detrás de un flag, o un arreglo descrito como completo cuando solo cubre uno de tres casos. El modo de fallo de las entradas escritas por desarrolladoras es ilegible-pero-preciso; el modo de fallo de las entradas escritas por PMs es legible-pero-sin-verificar. Ningún rol es dueño de las dos mitades de lo que necesita una buena entrada.

¿Cómo es realmente un modelo de propiedad que funciona?

Un borrador de quien esté más cerca del cambio, revisado por quien esté más cerca de la usuaria, con una persona nombrada responsable de la redacción final en vez de que todas asuman que alguien más atrapará los problemas. El borrador necesita existir y ser preciso más de lo que necesita ser bueno; una frase tosca escrita por una desarrolladora que diga correctamente qué cambió es un mejor punto de partida que una pulida pero sin verificar, porque reescribir por claridad es más fácil que reescribir por corrección. El paso de revisión es donde una PM o responsable de soporte lee el borrador y hace la única pregunta que atrapa la brecha de legibilidad: entendería esto si no hubiera visto el código.

¿Debería ser siempre la misma persona la responsable, o rota?

Nombrada y estable gana a rotativa, al menos para la aprobación final. Una responsable rotativa significa que cada entrada la revisa alguien que re-deriva las convenciones del equipo desde cero, que es exactamente cómo la voz se desvía entrada tras entrada y una lectora empieza a notar que el changelog lo escribió un comité. Una sola persona, o un grupo estable muy pequeño, acumula los criterios con el tiempo, cuándo decir “mejorado” frente a nombrar la cifra específica, cuándo un arreglo necesita su propia entrada frente a plegarse en un lote, y ese criterio vale más que distribuir el trabajo por igual.

Borrador (desarrolladora, del PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisado (dueña del changelog, contrastado con el PR real):
"Corregido: las exportaciones ordenadas por fecha podían
devolver resultados fuera de orden más allá de la primera
página. Ahora consistente en todas las páginas."

¿Un equipo pequeño necesita tanto proceso para una línea de texto?

No los roles como personas separadas, pero los dos pasos siguen importando incluso en solitario. Un equipo de una persona es a la vez la desarrolladora y la revisora, y la disciplina que sobrevive a esa escala es hacer la revisión como un pase mental separado, no saltar directamente de escribir el arreglo a publicar una descripción de él en el mismo aliento. La trampa a pequeña escala es saltarse el segundo pase por completo, no la falta de una segunda persona, porque nadie externo lo obliga, y la brecha de precisión que ese pase existe para atrapar no desaparece solo porque la misma persona pudiera en teoría notar su propio punto ciego.

¿Qué pasa cuando nadie es responsable de la entrada final?

El changelog se degrada de forma desigual en vez de fallar del todo, lo cual es peor porque nadie lo nota hasta que una lectora lo señala. Algunas entradas se mantienen precisas porque a quien las escribió le importó; otras se vuelven vagas, “varias mejoras y correcciones de errores”, porque quien las escribió iba rápido y nadie lo detectó antes de publicar. Las restricciones de formato de Keep a Changelog atrapan la deriva estructural, fechas faltantes, categorías equivocadas, pero nada en una plantilla atrapa una entrada vaga que está técnicamente bien formateada, que es exactamente la brecha que una dueña nombrada está ahí para cerrar.

FAQ

¿La dueña del changelog debería ser un rol de ingeniería o de producto? Cualquiera puede funcionar si la persona tiene tanto fluidez técnica para verificar el alcance como suficiente distancia de la implementación para escribir para una lectora externa; el título importa menos que si puede hacer las dos mitades, o sabe a quién preguntarle por la mitad que no puede.

¿Alguna vez es apropiado un horario rotativo tipo guardia para la propiedad del changelog? Para volumen, a veces, si el equipo es demasiado pequeño para que una persona lo revise todo; para voz y criterio, no, porque eso es exactamente lo que erosiona la rotación. Una rotación que comparte la carga de redacción mientras mantiene una revisora estable obtiene el beneficio sin la deriva.

¿Cuál es la señal más rápida de que algo va mal con la configuración actual de propiedad? Entradas que son precisas pero ilegibles, o legibles pero equivocadas en alcance, en un patrón que sigue a quién las escribió. Si la calidad correlaciona con la autora en vez de mantenerse consistente, la propiedad es la brecha, no la habilidad de escribir.

¿La automatización reduce cuánto importa la propiedad? Reduce cuánta escritura hace falta, no cuánto criterio hace falta. Automatización de changelog cubre lo que un pipeline puede generar con seguridad, formateo, publicación, cross-posting; la redacción, la agrupación y qué cuenta como digno de mención siguen siendo decisiones humanas sin importar cuánto del pipeline esté automatizado.

¿Qué pasa si quien abrió el PR y quien revisa no están de acuerdo con la redacción? Decide quien revisa, porque la pregunta que responde, entendería esto una lectora externa, es la que ese rol existe para proteger. Eso no vuelve inútil la lectura de la desarrolladora: si el desacuerdo es sobre precisión en vez de redacción, quien revisa cede, porque el alcance es la mitad que le toca acertar a quien escribió el código. Separar los dos tipos de desacuerdo, redacción frente a precisión, evita que la mayoría de estos casos se conviertan en un punto muerto.

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