← Documentos

Estrategia de ramas

2. Estrategia de branches Git y Neon

ExpressMX trabaja en modelo trunk-based: una sola rama de larga vida (main) que siempre debe estar desplegable, ramas cortas por feature, y branches efímeros de Postgres (Neon) por cada Pull Request. Este documento cubre las convenciones de nombre y los tres escenarios operativos: feature, hotfix y rollback.

Última actualización: 2026-05-05

2.1 Convenciones de nombre

Git

Prefijo Patrón Ejemplo Vida
feature/ feature/<modulo>-<descripcion-corta> feature/finanzas-corte-quincenal corta, una por PR
fix/ fix/<modulo>-<descripcion> fix/auth-jwt-secret-validation corta, una por PR
hotfix/ hotfix/<incidente> hotfix/login-401-loop mínima, prioridad alta
revert/ revert/<commit-corto> revert/3f9a2b-rbac-roles corta, audit trail

Reglas de oro:

Neon Postgres

Tipo Patrón Origen Vida
production nombre fijo primary permanente
dev nombre fijo child de production permanente, reset semanal
preview/pr-<NUM> un branch por PR child de production hasta 7 días
restore/<motivo> branch ad-hoc replay WAL temporal, hasta confirmar

2.2 Escenario A — Feature

  1. Developer crea feature/<modulo>-<descripcion> desde main actualizado.
  2. Pre-commit hooks corren typecheck y lint sobre el diff.
  3. Al abrir el PR: - GitHub Actions corre quality, test, build en paralelo (ver cicd-pipeline.md). - Vercel publica preview deployment. - Neon crea preview/pr-<NUM> y devuelve DATABASE_URL para el preview.
  4. Reviewer aprueba; checks verdes; merge squash a main.
  5. Vercel despliega production. Neon elimina el preview branch.

2.3 Escenario B — Hotfix

  1. Crear hotfix/<incidente> desde main (mismo flujo que feature, sin atajos).
  2. Diff mínimo dirigido al bug; sin refactors oportunistas.
  3. PR con etiqueta hotfix; review obligatoria de un segundo ingeniero.
  4. Tras el merge se promueve el deploy de Vercel y, si aplica, se documenta el incidente en un postmortem corto.

2.4 Escenario C — Rollback

Dos vectores independientes:

Rollback de código

Vercel ofrece "Promote previous deployment" en el dashboard. Es el camino preferido cuando el bug está sólo en código y el schema es compatible con la versión anterior.

Rollback de schema

Si la migración rompió producción se usa el time-travel de Neon:

neonctl branches restore production \
  --source 'production@1 hour ago'

El comando crea un branch nuevo con el estado anterior; se redirige DATABASE_URL a ese branch hasta confirmar la corrección. Después se crea un PR de revert documentado contra main para alinear el historial.

2.5 Disciplina de merges y migraciones

↑ Volver arriba