Un changelog no es un contrato: separa los hechos de git de las promesas de migración

Las notas de versión que escribe un modelo fallan en un punto muy concreto: convierten frases narrativas en contratos que el usuario cree poder seguir al actualizar. Un modelo puede inventariar commits, rutas y símbolos sin problema, pero no puede prometer una ruta de migración. La propuesta es repartir las dos cosas en archivos distintos y rechazar cualquier texto de changelog que cuele una garantía sin firmar.

Un archivo de hechos y otro de promesas

El primer artefacto es mecánico. Un script compila release_facts.json a partir de git describe --exact-match --tags, un git log del tag anterior a HEAD con hash y asunto de cada commit, y un git diff --numstat para el churn por ruta. Se ejecuta desde un checkout limpio en el tag y no lo toca ningún modelo ni ningún revisor: no clasifica rupturas de compatibilidad ni emite comandos de migración, solo levanta acta de lo que ha pasado. Los asuntos de commit describen trabajo que aterrizó, no trabajo en el que el usuario pueda confiar tras subir de versión.

El segundo artefacto es upgrade_contract.yml y sale vacío salvo el nombre del tag. Lo rellena una persona capaz de ejecutar los comandos de migración. Las filas que un modelo puede esbozar son las de inventario: asuntos y hashes, churn por ruta, nombres públicos añadidos o eliminados. Las que exigen mano humana son las que comprometen algo: la etiqueta de ruptura o aditivo, el comando de migración que todavía funciona, si los flags antiguos se siguen aceptando con la grafía vieja, si los datos quedan legibles después del salto y hasta cuándo se da soporte a la versión mayor anterior.

La puerta falla en cerrado

Si una celda del contrato queda en blanco, el changelog no pasa. El silencio no equivale a un "sin cambios incompatibles" firmado. Hay además un detalle de orden que importa: el modelo no debe ver el contrato mientras redacta. Si lo ve, copia el tono de garantía en cada párrafo y vuelve a mezclar inventario con promesa. El borrador se genera solo con el archivo de hechos, y las frases del revisor se injertan después, en un paso aburrido y separado. Antes del merge hay una comprobación que revisa los verbos de promesa.

Los dos archivos se guardan junto al tag para que una auditoría posterior distinga lo que se compiló de lo que alguien firmó. El flujo no es una convención de estilo: si no hay contrato, no hay publicación.

El coste es humano y el flujo lo asume. Si nadie rellena el contrato, la puerta no se abre y ese release se queda sin notas. Es la diferencia entre que la ruta de actualización la valide un revisor o que la estrene el primer ticket de soporte.