Workflow: Code Deployment / Release

Runbook operativo. Define el proceso completo desde que un desarrollador crea una rama de feature hasta que el código está en producción y verificado. Implementa los controles de la Política de Gestión de Cambios y asegura que ningún código no revisado llegue a producción. Aprobado por la Asamblea en [__]. Versión: 1.0.

1. Trigger

Un miembro del equipo completa el desarrollo de una feature, fix o cambio de configuración listo para producción.
Se activa un release programado (ej. sprint bi-semanal).
Se requiere un hotfix urgente por un incidente P0/P1 (ver Workflow: Bug / Incident Triage, orden 54).
Se actualiza una dependencia de seguridad crítica.

2. Roles y Responsabilidades (RACI)

Tarea	Responsable	Aprobador	Consultado	Informado
Desarrollo y apertura del PR	Ingeniero de desarrollo	—	—	—
Code review (primer revisor)	Otro ingeniero del equipo	—	Luishy (si es crítico)	—
Aprobación final del PR	Luishy Medina (CTO)	—	—	—
Merge a `main`	Luishy Medina	—	—	—
Deploy automático (CI/CD)	GitHub Actions (automatizado)	—	—	Luishy
Verificación post-deploy	Luishy Medina	—	Ingeniero de PR	CCO (si afecta clientes)
Rollback (si necesario)	Luishy Medina	Carlos Miranda Levy (P0)	—	CCO
Comunicación de release a clientes	Ydarlis Cabrera (CCO)	—	Luishy	—

3. Ambientes

Ambiente	URL / Acceso	Propósito	Quién puede hacer deploy
Development (`dev`)	Local / rama de feature	Desarrollo y pruebas individuales	Cualquier ingeniero
Staging / Preview	URL temporal por PR (GitHub Pages preview o Vercel/Netlify preview)	QA, revisión de diseño, validación con stakeholders	CI automático en cada PR
Production (`main`)	`lawra.io` (GitHub Pages)	Usuarios reales	Solo vía merge a `main` aprobado; deploy automático

Regla fundamental: ningún commit llega a producción sin pasar por PR review + CI gates aprobados.

4. Pasos Numerados

Fase 1 — Desarrollo en Rama de Feature (Day 0–N)

Paso 1 — Crear rama desde main: El ingeniero crea una rama con nombre descriptivo siguiendo la convención:

feature/{ticket-id}-descripcion-breve
fix/{ticket-id}-descripcion-breve
hotfix/{ticket-id}-descripcion-breve
chore/{descripcion} (para actualizaciones de dependencias, config, etc.)

Paso 2 — Desarrollo local: El ingeniero desarrolla en su rama. Commits con mensajes descriptivos en inglés o español (convención del equipo). Se recomienda: git commit -m "feat: add contract export to PDF (#123)".

Paso 3 — Tests locales: El ingeniero ejecuta localmente:

npm run build (build de producción sin errores)
Tests unitarios / de integración disponibles.
Verificación manual en entorno local de los cambios.

Fase 2 — Pull Request y CI (Day N)

Paso 4 — Apertura del Pull Request: El ingeniero abre un PR hacia main en GitHub. El PR debe incluir:

Descripción clara: qué cambia y por qué.
Screenshots / GIFs si hay cambios de UI.
Cómo probar: pasos para que el revisor verifique.
Checklist en el template de PR: migraciones pendientes, cambios de configuración, impacto en datos.
Etiquetas: feature, fix, hotfix, breaking-change, security, etc.

Paso 5 — CI Gates automáticos (GitHub Actions): Al abrir o actualizar el PR, GitHub Actions ejecuta automáticamente:

npm run build — build de producción completo. Falla → PR bloqueado.
Tests automáticos (Vitest, Playwright o equivalentes disponibles). Falla → PR bloqueado.
Linting (ESLint / Prettier). Falla → PR bloqueado.
Análisis de seguridad de dependencias (npm audit / Dependabot). Vulnerabilidad crítica → PR bloqueado.
Preview deploy a ambiente de staging (URL única por PR).

SLA del CI: el pipeline completo debe ejecutarse en < 15 minutos. Si supera 15 min, Luishy revisa optimizaciones.

Decisión A: ¿CI gates pasados?

Sí → Notificación al revisor de que el PR está listo.
No → El ingeniero corrige los fallos y hace push. El CI se re-ejecuta automáticamente.

Fase 3 — Code Review (Day N a Day N+2)

Paso 6 — Revisión de código (primer revisor): Mínimo 1 revisor aprobado es obligatorio antes del merge. El revisor evalúa:

Corrección lógica del código.
Adherencia a patrones del proyecto (ver CLAUDE.md del repo).
Seguridad: ninguna credencial hardcodeada, no se exponen datos sensibles, inputs sanitizados.
Performance: no se introducen N+1 queries o cuellos de botella obvios.
Accesibilidad: cambios de UI mantienen WCAG AA mínimo.
Cobertura de tests: cambios con lógica compleja tienen tests asociados.

SLA de review: el revisor debe completar la revisión en < 24 horas para PRs normales, < 4 horas para hotfixes P0/P1.

Paso 7 — Ciclo de revisión: Si el revisor solicita cambios (Request Changes), el ingeniero realiza los ajustes y solicita re-review. Máximo 2 ciclos de revisión; si hay desacuerdo persistente, Luishy es el árbitro final.

Paso 8 — Aprobación final: Para PRs que afectan:

Lógica de seguridad / autenticación / autorización.
Esquema de base de datos (Firestore rules, índices).
Configuración de Firebase o proveedores de IA.
Archivos de configuración de producción (.env, firebase.json, firestore.rules).

Luishy Medina debe ser el aprobador final (además del primer revisor).

Fase 4 — Merge a `main` y Deploy (Day N+1 a Day N+2)

Paso 9 — Merge a main: Luishy (o el ingeniero designado con permiso) hace el merge del PR a main. Estrategia: Squash and Merge para mantener el historial de main limpio (un commit por feature/fix).

No se permite push directo a main. Branch protection rules en GitHub exigen PR + CI + al menos 1 aprobación.

Paso 10 — Deploy automático vía GitHub Actions: El push a main dispara automáticamente el workflow de deploy:

npm run build — build final de producción (incluye Pagefind index si aplica).
Validación de que el build fue exitoso.
Deploy a GitHub Pages (u hosting configurado).
GitHub Actions registra el deploy con commit SHA, timestamp, y actor.

SLA de deploy: el proceso de build + deploy debe completarse en < 20 minutos desde el merge.

Fase 5 — Verificación Post-Deploy

Paso 11 — Smoke test manual: Luishy o el ingeniero del PR verifica en producción (dentro de los 10 minutos post-deploy):

Las páginas principales cargan correctamente.
La feature / fix desplegado funciona como esperado.
No hay errores 500 en las páginas críticas.
El sistema de monitoreo no muestra alertas nuevas.

Paso 12 — Verificación de funcionalidades críticas: Para releases que afectan flujos críticos (autenticación, pagos, AI Suite), se ejecuta un checklist de verificación (documento en el repositorio) que cubre los pasos clave del usuario.

Decisión B: ¿Verificación post-deploy exitosa?

Sí → El deploy se considera exitoso. Luishy cierra el issue/ticket asociado.
No → Paso 13 (Rollback).

Fase 6 — Rollback (si necesario)

Paso 13 — Decisión de rollback: Si la verificación post-deploy falla o se detecta un problema P0/P1 en producción dentro de los 30 minutos del deploy, Luishy evalúa:

¿Se puede hacer un fix rápido (< 30 min) y re-deploy? → Fix rápido.
¿El impacto es alto y un fix rápido no es viable? → Rollback inmediato.

Para P0: Carlos Miranda Levy debe ser notificado antes del rollback.

Paso 14 — Ejecución del rollback: GitHub Actions puede re-ejecutar el deploy del commit anterior. Luishy dispara el re-deploy del último SHA estable conocido. El rollback debe completarse en < 15 minutos.

Paso 15 — Documentación del rollback: Luishy documenta en el PR o en un issue separado:

Razón del rollback.
Timestamp de detección del problema y del rollback.
Plan de fix antes del próximo intento de deploy.

Fase 7 — Release Notes y Comunicación

Paso 16 — CHANGELOG (para releases significativas): Para releases que incluyen nuevas features, cambios de comportamiento, o correcciones que afectan a los usuarios, Luishy o el ingeniero actualiza el CHANGELOG.md del repositorio con:

Versión y fecha.
Nuevas features.
Bug fixes.
Breaking changes (si aplica).

Paso 17 — Comunicación a clientes (si aplica): Para releases con impacto en la experiencia del usuario o nuevas funcionalidades significativas, CCO prepara una comunicación por email y/o notificación en el portal. Se coordina con Luishy para el contenido técnico.

5. Proceso de Hotfix (Excepción P0/P1)

Para incidentes P0/P1 que requieren un fix urgente:

Se crea una rama hotfix/{descripcion} directamente desde el último tag de producción estable.
CI gates no se pueden saltear, pero se acepta review express (mínimo 15 min, un revisor, Luishy como aprobador obligatorio).
El fix se mergea a main directamente después de la aprobación.
Luishy puede omitir el preview deploy (staging) pero nunca el CI gate de build.
Verificación post-deploy con prioridad máxima.
Post-mortem del incidente según Workflow: Bug / Incident Triage.

6. Puntos de Decisión

Decisión	Opciones
A — ¿CI gates pasados?	Sí → avisar revisor / No → ingeniero corrige antes de continuar
B — ¿Verificación post-deploy OK?	Sí → deploy exitoso / No → evaluar fix rápido o rollback
C — ¿Fallo post-deploy: fix rápido viable?	Sí (< 30 min) → fix y re-deploy / No → rollback + documentar

7. Outputs / Artifacts

PR con descripción, código revisado y aprobado.
CI/CD pipeline logs en GitHub Actions.
CHANGELOG actualizado (para releases significativas).
Registro de deploy (commit SHA, timestamp, actor) en GitHub Actions.
Comunicación de release a clientes (si aplica).

8. Checklist Final

9. Métricas / KPIs

Métrica	Objetivo
Lead time (PR abierto → merge)	< 2 días hábiles
Duración del CI pipeline	< 15 minutos
Duración del deploy a producción	< 20 minutos
Tasa de rollbacks sobre total de deploys	< 2 %
PRs mergeados sin al menos 1 aprobación	0 %
Deploys directos a `main` sin PR	0
Vulnerabilidades críticas en npm audit al momento del deploy	0

10. Referencias

Política de Gestión de Cambios
Workflow: Bug / Incident Triage (orden 54) — para hotfixes
Política de Control de Acceso (orden 30) — branch protection
Política de Seguridad de la Información (orden 29)
NIST SP 800-128 — Guide for Security-Focused Configuration Management
SOC 2 CC8.1 — Changes to infrastructure, data, software and procedures

11. Auditoría

Registro	Retención	Evidencia SOC 2
Historial de PRs + aprobaciones en GitHub	5 años	CC8.1 — Change management
Logs de CI/CD pipeline (GitHub Actions)	5 años	CC8.1
Registro de deploys (commit SHA, actor, timestamp)	5 años	CC8.1
Documentación de rollbacks	5 años	CC8.1
CHANGELOG	Permanente	CC8.1

Adoptado por la Asamblea General de Socios en fecha [__]. Próxima revisión: [fecha + 12 meses].

Por LAWRA, S.R.L. — Gerente

Workflow: Code Deployment / Release

Workflow: Code Deployment / Release

1. Trigger

2. Roles y Responsabilidades (RACI)

3. Ambientes

4. Pasos Numerados

Fase 1 — Desarrollo en Rama de Feature (Day 0–N)

Fase 2 — Pull Request y CI (Day N)

Fase 3 — Code Review (Day N a Day N+2)

Fase 4 — Merge a main y Deploy (Day N+1 a Day N+2)

Fase 5 — Verificación Post-Deploy

Fase 6 — Rollback (si necesario)

Fase 7 — Release Notes y Comunicación

5. Proceso de Hotfix (Excepción P0/P1)

6. Puntos de Decisión

7. Outputs / Artifacts

8. Checklist Final

9. Métricas / KPIs

10. Referencias

11. Auditoría

Comments

Fase 4 — Merge a `main` y Deploy (Day N+1 a Day N+2)