Ramas y flujo de trabajo

Dos ramas permanentes (main y dev) más ramas cortas de trabajo. dev es la rama de integración y se despliega sola en el entorno dev; main es producción y solo recibe lo que ya pasó por dev (o un hotfix).

feature/* · fix/* ──PR──▶ dev ──PR release──▶ main
   (corta)              (entorno dev)        (producción)

Reglas de oro

1. Nunca se commitea directo a main ni a dev: todo llega por PR con el check Lint & build en verde.
2. Una rama = un propósito. No mezcles un refactor con una feature ni dos features en la misma rama.
3. Ramas cortas. Si algo lleva semanas, divídelo en entregas pequeñas que se integren por separado.
4. dev siempre desplegable. Es lo que ve el resto del equipo en el entorno dev; lo que se rompe se arregla con fix/* o se revierte cuanto antes.
5. El flujo verificado a mano se persiste como spec de Playwright en tests/e2e/. Un chequeo manual que no quedó como spec no cuenta como cobertura.
6. Migraciones expand/contract: nunca DROP / RENAME / NOT NULL en el mismo deploy que todavía usa la forma vieja (ver Deploy y CI/CD).

Nombres de rama

• feature/products-export-csv, fix/communications-dst-ventana.
• Con ticket delante si existe: feature/123-products-export-csv.
• Minúsculas, guiones, sin espacios ni acentos. El slug describe el resultado (export-excel), no la acción.

Nueva feature, paso a paso

# 1. Parte de un dev actualizado
git switch dev
git pull origin dev

# 2. Crea la rama
git switch -c feature/products-export-csv

# 3. Implementa. El pre-commit arregla el lint de lo staged automáticamente.

# 4. Antes de subir, corre el spec del flujo tocado (la suite completa no hace falta aquí)
pnpm exec playwright test tests/e2e/app/products.spec.ts

# 5. Sube: el hook pre-push corre la suite completa
git push -u origin feature/products-export-csv

# 6. Abre el PR hacia dev
gh pr create --base dev --title "..." --body "..."

# 7. CI en verde → merge con squash → dev se despliega solo.
# 8. Verifica en el entorno dev.

Release a producción

Cuando lo integrado en dev está estable, se promociona con un PR dev → main (merge commit, sin squash, para conservar la historia de dev):

git switch dev && git pull origin dev
gh pr create --base main --head dev --title "Release: <resumen>" --body "..."
# CI en verde → merge → deploy de producción con health check

Fix de bug, paso a paso

Igual que una feature, con fix/ y con el spec de regresión: primero el spec que reproduce el bug (falla), después el arreglo, después el spec en verde.

git switch dev && git pull origin dev
git switch -c fix/communications-dst-ventana
# 1) spec que reproduce el bug  2) arreglo mínimo  3) spec en verde
git push -u origin fix/communications-dst-ventana   # pre-push: suite completa
# PR a dev → CI → squash merge → entorno dev

Un fix normal no va directo a main: main solo recibe lo que ya pasó por el entorno dev (la excepción es el hotfix).

Hotfix (bug crítico en producción)

git switch main && git pull origin main
git switch -c hotfix/login-callback
# arreglo mínimo + spec de regresión
git push -u origin hotfix/login-callback
# PR a main (excepción deliberada: no pasa por dev) → CI → merge → deploy de producción

git switch dev
git merge main   # o un PR main → dev
git push origin dev

Commits

• Formato recomendado (no obligatorio): tipo: descripción, con feat / fix / chore / docs / refactor / test.
• Título corto; el cuerpo explica por qué, no el qué (el diff ya dice el qué).
• El pre-commit pasa ESLint sobre lo staged: no hace falta un commit aparte para formato.

Pull requests

• Título y descripción: qué cambia y cómo probarlo.
• Checklist antes de pedir review:
  • Spec de Playwright del flujo tocado (o pnpm test:e2e:smoke) corriendo en local.
  • pnpm lint limpio y, si hay texto visible, i18n en en / es / pt.
  • Entidad nueva: eventos de dominio, audit log y triggers (ver AGENTS.md).
  • Migración: expand/contract, generada con pnpm db:generate en el mismo PR.
  • PR pequeño (≤ ~400 líneas) cuando sea posible.

Protege main y dev en GitHub (Settings → Branches) exigiendo el check Lint & build y prohibiendo force push.

Qué corre y cuándo