0005 — Promoción a producción por rama, no por dev entero

Estado: aceptada · Fecha: 2026-09-19

Contexto

promote.yml hacía git merge --ff-only origin/dev || git reset --hard origin/dev sobre main, así que main era siempre una copia de dev. Eso tenía tres consecuencias:

• No se podía elegir qué subía. Cualquier cosa integrada en dev iba a producción en el siguiente promote, la hubiera aprobado QA o no.
• Las ramas nacían de dev, con trabajo ajeno sin aprobar dentro. Aunque se abriera un PR de una sola rama a main, arrastraba todo lo demás.
• Los arreglos hechos a mano en main se perdían o bloqueaban el promote. El 2026-09-19, main tenía tres cherry-picks que no estaban en dev. El --ff-only fallaba, el reset --hard dejaba un push sin fast-forward y GitHub lo rechazaba, así que el promote ya no podía correr.

Decisión

Un solo camino a producción: el PR de una rama concreta a main.

• Toda rama sale de main. Primero va por PR a dev para que QA la pruebe en Test. Cuando QA la aprueba, la misma rama va por PR a main.
• dev nunca se fusiona en main. Es solo el entorno de QA.
• sync-main-to-dev.yml fusiona main en dev en cada push a main. Los choques en docs/generated/ los resuelve regenerando; los de código los deja en un PR.
• promote.yml ya no mueve código. Corta la versión sobre main: notas con git-cliff, etiqueta, y relanza el deploy y el sync, porque su push con el GITHUB_TOKEN no dispara workflows.
• La aprobación de QA es el merge del PR a main. La organización está en el plan gratuito: no hay required reviewers en environments y la protección de ramas no se puede imponer en un repo privado. Es una regla de equipo, no algo que GitHub bloquee.

Descartado

• Mantener también "promover dev entero". Con dos caminos, las ramas vuelven a salir de dev por costumbre y deja de saberse qué hay en producción. Promover "todo lo aprobado" se hace igual: fusionando los PRs aprobados uno detrás de otro.
• Cherry-pick de dev a main. Da commits duplicados con otro SHA (git cherry los marca como distintos) y conflictos en cada sincronización. Se usa una sola vez, en la transición, para pasar lo que ya estaba en dev.
• Feature flags como mecanismo principal. Siguen siendo la opción para funcionalidades grandes o de larga duración, pero no hacen falta para cambios pequeños.

Consecuencias

• Migraciones: supabase db push --include-all acepta que lleguen fuera de orden. La regla es que la migración de una rama no dependa de la de otra rama sin aprobar; si depende, suben juntas.
• Riesgo: QA prueba en dev una combinación distinta de la que llega a main. Para cambios grandes, conviene una comprobación rápida en producción después del deploy, o un flag.
• Artefactos de yarn gen: chocan entre ramas. El PR a main tiene que llevarlos regenerados sobre main, y el CI lo comprueba.
• Guía operativa: Flujo de ramas. Los agentes la tienen en la skill flujo-de-ramas y en la regla de Cursor .cursor/rules/flujo-de-ramas.mdc.