# ADR-0019 — El ciclo de versión: manifiesto de US, dos mitades con una firma en el medio, y el aviso como evento - **Estado:** aceptado - **Fecha:** 2026-09-09 - **Decide:** lead / arquitecto de la metodología ## Contexto Hay equipos —grandes y medianos, no solo los desprolijos— que **no arman ramas de release ni etiquetan versiones**. Desplegar a producción se vuelve un ejercicio de memoria: hay que acordarse de qué ramas componen la funcionalidad y mergearlas a la rama de producción una por una, en el momento del despliegue. Eso tiene tres consecuencias, y las tres se ven en repos reales: 1. **Se despliega una combinación que nunca se probó.** Cada orden de merge produce un árbol distinto; el que llega a producción no existió en ningún ambiente antes. 2. **No se puede contestar qué hay en cada ambiente.** Ni qué funcionalidades comprende. Cuando algo falla a las tres de la mañana, no hay a qué volver. 3. **Se cuelan funcionalidades que no estaban listas**, porque la selección de qué va se hace rama por rama y a mano. dai ya sabía atar una User Story a su código (`implements.yaml`) y a su commit (`dai stamp`). Lo que faltaba era el último eslabón: atar la US a la **versión desplegada**. Sin eso, la trazabilidad llega hasta la PR y se corta justo donde el negocio pregunta. ## Decisión ### 1. dai aporta el manifiesto, no la estrategia de branching La estrategia de ramas la elige cada equipo, y dai no opina: es una herramienta, no un mandato. Lo que dai aporta es el eje que ya es suyo, extendido un paso: ``` implements.yaml → commit → PR → VERSIÓN → AMBIENTE (ADR-0004) (ADR-0005) ←── esto es lo nuevo ──→ ``` `dai release plan` produce el **manifiesto**: qué User Stories entran entre el último tag y la rama de integración, en qué estado está cada una, y qué entró **sin** declarar US. Los otros comandos son formas distintas de publicar ese mismo dato — el CHANGELOG, el tag, el comentario en cada ticket, el aviso al canal. **Cómo se resuelve qué US entró:** leyendo los `implements.yaml` tal como estaban en cada commit del rango, no por el nombre de la rama. El link viaja con el código, así que la respuesta sobrevive a que la rama se borre y a que el change se archive — que es exactamente el estado del repo cuando se llega a cortar la versión, días después del merge. **Alternativa descartada:** deducirlo del nombre de la rama en el commit de merge. Es más simple y es frágil: desaparece con squash, con rebase, y con cualquier equipo que renombre. Se conserva solo como señal secundaria, para detectar lo que entró **sin** link. ### 2. El bump se propone; lo firma una persona dai deriva un piso del tipo de los commits (`feat:` → minor, `!` → major) y **lo dice**: es una propuesta, no un veredicto. La regla que manda mira el **comportamiento observable**. La evidencia es de este mismo repo: la versión 0.14.0 salió con cuatro commits `fix:` y era minor, porque cambió un default que ve quien no configura nada. Cualquier herramienta que derive la versión de los tipos de commit —semantic-release, standard-version, Conventional Commits puro— habría cortado un patch equivocado. **Alternativa descartada:** versionado automático desde los commits. Es precisamente el pedazo que no hay que automatizar: convierte una decisión de comunicación en un efecto secundario de cómo alguien tituló un commit. ### 3. El corte son dos comandos, porque hay una firma humana en el medio ``` plan ──▶ [FIRMA: la versión] ──▶ cut ──▶ dai pr ──▶ [FIRMA: merge + publicar] │ done ◀────────┘ ``` `cut` **prepara y no habla hacia afuera**: rama de release, número, entrada de CHANGELOG, commit. Ni push, ni tag, ni PR. `done` **cierra después del merge**: tag anotado, release note, back-merge y aviso. Existe como comando separado porque los dos pasos que más se olvidan cuando la ceremonia se hace a mano —el release note y el back-merge— viven en esta mitad, la que queda después de la firma. **Una vez creado el tag, ningún paso posterior aborta.** El tag es la versión: si existe, la versión existe. Fallar y salir dejaría el corte a medio camino sin decir en qué mitad quedó, así que cada paso reporta y sigue. ### 4. El tag es la versión; los archivos son espejos `dai release cut` sube el número en `VERSION` y `package.json` **si existen**, informa cuáles tocó, y no se planta si no hay ninguno. Un repo .NET o un frontend corporativo versionan igual de bien sin ninguno de los dos. El bump de `package.json` es **quirúrgico** —solo la línea de la versión—: reserializar el JSON reformatea los objetos compactos y llena el diff de la release de ruido que nadie pidió. ### 5. El CHANGELOG lo escribe una persona; dai deja el material `cut` inserta la entrada con las US del manifiesto **en un comentario HTML** (se ve al editar, desaparece al renderizar) y las secciones vacías. La prosa no la escribe dai: sabe *qué* entró, no *por qué importa*. **Alternativa descartada:** generar el changelog desde los subjects de los commits. Produce una lista que nadie lee, y encima da la sensación de que el trabajo está hecho. ### 6. Estampar la versión en cada US es opcional, y avisa su alcance `dai release stamp --env ` deja en **cada US del release** un comentario con versión, app, ambiente y fecha. Con eso el funcional lee el ticket en vez de preguntar, y una US federada en varios repos acumula sola su matriz (backend en producción, frontend en pre). Tres cuidados, porque escribe N veces hacia afuera en tickets de gente distinta: - **Muestra el alcance real antes de escribir** — cuántos comentarios y en qué tickets, descontando los que ya están. Un número inflado enseña a ignorar el aviso. - **Es idempotente por `(app, versión, ambiente)`**, con una marca en el propio comentario. Redesplegar no llena el ticket de repetidos; la misma versión en otro ambiente sí es un evento nuevo. - **Si no puede leer los comentarios, lo dice** en vez de suponer que no estampó. Es la misma distinción que ADR-0003 hace entre "no hay US" y "no hubo respuesta"; acá afirmar de más se paga en duplicados que nadie puede borrar. **Decir que no sale con 0.** Para cuando el comando corre, el tag y el release note ya existen: la versión está hecha. Que un equipo elija no hacer ruido en veinte tickets es una decisión legítima, no un error a corregir. ### 7. El aviso al canal es un tercer adaptador, y su mensaje tiene estructura sin formato `DAI_NOTIFY` elige el backend igual que `DAI_PM` elige el tracker: `discord`, `slack`, `webex`, `telegram`, un `webhook` genérico, o `none` (el default: dai no habla hacia afuera sin que se lo pidan). El mensaje es **uno solo para todos los canales**, con estructura —qué salió, quién, cuándo, qué trae, dónde mirar— y **sin formato**. La distinción es de costo, no estética: la estructura son saltos de línea y viñetas, y se ve igual en los cinco; el formato son cuatro dialectos incompatibles (Discord con `**negrita**` y sin links con nombre, Slack con `*negrita*` y ``, Webex con markdown completo, Telegram con `parse_mode` y el escapeo de MarkdownV2 que devuelve 400 por un punto suelto). Con esa decisión, el adaptador es una tabla de cinco líneas en lugar de un módulo de render. **Las viñetas son las User Stories, no los subjects de los commits.** Un aviso que dice *"se implementa el conversor de propiedades no serializables"* lo entiende quien escribió el código; uno que dice *"Checkout sin duplicado"* lo entiende el negocio. Es la misma distinción entre el QUÉ y el CÓMO que sostiene el método, aplicada al canal. **El endpoint es la credencial:** quien lo tiene, postea. Vive en `.env.dai` (ADR-0017) y dai muestra el host, nunca la URL — tampoco en los mensajes de error. **Qué versión hay en cada ambiente NO vive en el repo.** Un despliegue es un evento, no un archivo: cambia sin que cambie el código. Guardarlo en un archivo obligaría al CI a commitear en cada deploy. Su registro es el stamp en el tracker y el release del forge. ### 8. `done` borra la rama de release que acaba de cerrar Es el único punto del ciclo donde dai puede **afirmar** que borrarla es seguro: ya está mergeada en producción, etiquetada y con el back-merge hecho. Si no se hace ahí, se acumulan — este mismo repo tenía cinco cuando se implementó el comando. La red de seguridad la pone git, no una suposición: `git branch -d` (minúscula) se niega a borrar una rama sin mergear. Hay precedente en el CLI: `dai done` ya hace exactamente esto con la rama de una US. **Alternativa descartada:** un `dai release cleanup` que borre ramas de release viejas en masa. dai no las creó, no puede saber si alguien conserva una a propósito, y limpiar ramas en general no es su dominio. `dai release status` las nombra y deja el comando escrito; borrarlas es del equipo. ### 9. Lo que dai NO hace - **No despliega.** Llega hasta el tag y vuelve a aparecer después, estampando. Quién despliega es el pipeline. - **No mergea ni publica.** Son firmas humanas ([Art. 5](../MANIFIESTO.md#art-5)). - **No impone un modelo de branching.** La rama de release es opcional (`--no-branch`), y las dos ramas de vida larga las declara el repo (`DAI_BRANCH_DEV` / `DAI_BRANCH_PROD`). - **No es un framework de notificaciones.** Avisa eventos de release con su manifiesto. ## Consecuencias - Un equipo puede contestar, sin reunirse: **qué versión hay en cada ambiente y qué US comprende**. Desde el ticket, no desde un Excel. - El manifiesto expone, antes de cortar, **las US atrasadas** y **lo que entró sin link** — la última pantalla donde eso se puede ver. - El ciclo funciona igual con rama de release (ventana de estabilización) y sin ella (tag directo desde integración), así que dai no fuerza a nadie a cambiar de estrategia para ganar trazabilidad. - Aparecen dos variables nuevas de config (`DAI_NOTIFY`, `DAI_NOTIFY_WEBHOOK`, más `DAI_NOTIFY_CHAT_ID` solo para Telegram) y dos métodos nuevos en el adaptador de PM (`comment`, `listComments`), que cualquier backend nuevo tiene que implementar para soportar el estampado de versión. - La skill `/dai-release` conduce el ciclo pero **no recalcula nada**: narra lo que dicen los comandos. Si la skill y el CLI se contradicen, gana el CLI.