Versionado y Gitflow

1. Importancia del versionado

Sin un sistema de versionado formal, surgen problemas recurrentes que afectan la velocidad y la confiabilidad del equipo:

• No hay trazabilidad: es imposible saber qué versión corre en cada ambiente, ni qué cambios incluye.
• No hay control de releases: cualquier push puede llegar a producción sin un punto de corte claro.
• Rollbacks a ciegas: sin tags ni versiones, revertir un deploy implica buscar commits manualmente.
• Comunicación ambigua: frases como "ya está el fix" no dicen nada sobre qué ambiente ni qué versión.

Al adoptar versionado semántico y un flujo de ramas estructurado, el equipo obtiene:

• Trazabilidad completa: cada ambiente tiene una versión concreta asociada a un tag de Git.
• Comunicación clara: "la versión 0.9.1 ya está en TEST" es una afirmación verificable.
• Rollback controlado: revertir es tan simple como desplegar el tag anterior.
• Historial auditable: cada release queda documentada con su tag, su rama y sus cambios.

2. Semantic Versioning

Nvito utiliza Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) con reglas adaptadas al ecosistema:

Reglas de incremento

Ejemplos concretos de Nvito

3. Versiones actuales

4. Estructura de ramas (Gitflow)

Tipos de rama

Reglas de protección

• main y develop son ramas protegidas: no se permite push directo.
• Todo cambio llega vía merge request (MR) desde ramas de trabajo.
• Las ramas feature/*, fix/* y refactor/* se eliminan después del merge.

5. Mapeo de ramas a ambientes

Flujo de promoción entre ambientes

feature/* → develop → DEV (automático)
                ↓
         release/X.Y.Z → test → TEST (automático)
                                  ↓
                              main → PROD (automático, futuro)

6. Flujo de release

Pasos del flujo

1. Crear rama de release: git checkout -b release/X.Y.Z develop
2. Bump de versión: actualizar version en package.json de cada repositorio modificado.
3. Commit de versión: git commit -m "release: bump version to X.Y.Z"
4. Merge a test: git checkout test && git merge release/X.Y.Z → deploy automático a TEST.
5. QA y verificación: el equipo valida funcionalidad en el ambiente TEST.
6. Si hay bugs: corregir en la rama release/X.Y.Z, repetir desde el paso 4.
7. Merge a main: git checkout main && git merge release/X.Y.Z + crear tag vX.Y.Z.
8. Merge de vuelta: git checkout develop && git merge release/X.Y.Z para sincronizar.
9. Limpiar: eliminar la rama release/X.Y.Z.

Comandos del flujo completo

# 1. Crear rama de release desde develop
git checkout develop
git pull origin develop
git checkout -b release/0.9.1

# 2-3. Bump de versión y commit
# (El agente nvito-version-bumper lo hace automáticamente)
npm version 0.9.1 --no-git-tag-version
git add package.json
git commit -m "release: bump version to 0.9.1"

# 4. Merge a test para deploy a TEST
git checkout test
git pull origin test
git merge release/0.9.1
git push origin test

# 5-6. QA en TEST... si hay fixes, hacerlos en release/0.9.1 y repetir

# 7. Merge a main y tag
git checkout main
git pull origin main
git merge release/0.9.1
git tag -a v0.9.1 -m "Release 0.9.1"
git push origin main --tags

# 8. Merge de vuelta a develop
git checkout develop
git merge release/0.9.1
git push origin develop

# 9. Limpiar
git branch -d release/0.9.1
git push origin --delete release/0.9.1

7. Flujo de hotfix

Cuando se detecta un bug crítico en producción que no puede esperar al siguiente release:

Pasos

1. Crear rama de hotfix: git checkout -b hotfix/X.Y.Z main
2. Corregir el bug: implementar la corrección mínima necesaria.
3. Bump de versión PATCH: incrementar solo el tercer número.
4. Merge a main + tag: git merge hotfix/X.Y.Z + git tag vX.Y.Z.
5. Merge a develop: sincronizar la corrección con la rama de integración.

Comandos

# 1. Crear hotfix desde main
git checkout main
git pull origin main
git checkout -b hotfix/0.9.2

# 2. Corregir el bug
# ... implementar fix ...

# 3. Bump versión
npm version 0.9.2 --no-git-tag-version
git add package.json
git commit -m "hotfix: fix critical RSVP timezone calculation"

# 4. Merge a main
git checkout main
git merge hotfix/0.9.2
git tag -a v0.9.2 -m "Hotfix 0.9.2 — fix RSVP timezone"
git push origin main --tags

# 5. Merge a develop
git checkout develop
git merge hotfix/0.9.2
git push origin develop

# Limpiar
git branch -d hotfix/0.9.2
git push origin --delete hotfix/0.9.2

8. Ciclo de vida de una versión

Cada versión pasa por cuatro estados:

Transiciones

• Draft → En DEV: automático al hacer push a develop.
• En DEV → En TEST: manual al mergear release/X.Y.Z a test.
• En TEST → Producción: manual al mergear a main después de aprobación de QA.
• En TEST → En DEV (rollback): si se encuentra un bug, se corrige y se re-despliega.

9. Naming conventions

10. Agente nvito-version-bumper

El ecosistema Nvito cuenta con un agente automático que gestiona el versionado de forma inteligente:

Funcionamiento

1. Se ejecuta al pre-cierre de cada sesión de desarrollo como parte del flujo de agentes.
2. Analiza los cambios realizados en la sesión: archivos modificados, tipos de commit, módulos afectados.
3. Determina automáticamente el tipo de incremento:
   • Nuevos archivos de servicio, controlador o pantalla → MINOR
   • Modificaciones a archivos existentes sin cambio de API → PATCH
   • Cambios en contratos de API o modelos de datos → potencial MAJOR
4. Actualiza package.json de cada repositorio modificado en la sesión.
5. MAJOR siempre requiere confirmación explícita del usuario antes de aplicarse.

Criterios de decisión

11. Badge de ambiente en el admin

El dashboard administrativo (nvito-admin) muestra un badge de ambiente en el header que indica el ambiente actual y la versión desplegada.

Comportamiento

• Solo visible en ambientes no-producción: LOCAL, DEV y TEST. En producción no se muestra.
• Muestra el nombre del ambiente más la versión actual del package.json.
• Click para ver detalles: al hacer click, despliega un popover con versión, ambiente y URL del API.

Colores por ambiente

Configuración

La variable de entorno que controla el ambiente es:

NEXT_PUBLIC_APP_ENV=local   # local | dev | test | production

La versión se inyecta automáticamente desde package.json en build time, lo que garantiza que siempre refleja la versión exacta del código desplegado.

// next.config.ts (simplificado)
const packageJson = require('./package.json');

const nextConfig = {
  env: {
    NEXT_PUBLIC_APP_VERSION: packageJson.version,
  },
};

12. Referencia rápida

Comandos más usados

Checklist de release

• Todos los tests pasan en la rama release/X.Y.Z
• Build exitoso sin errores de TypeScript
• Versión actualizada en package.json
• Commit de release con formato release: bump version to X.Y.Z
• Merge a test exitoso, deploy verificado en TEST
• QA aprobado en ambiente TEST
• Merge a main realizado
• Tag vX.Y.Z creado y pusheado
• Merge de vuelta a develop completado
• Rama release/X.Y.Z eliminada (local y remota)

Checklist de hotfix

• Bug crítico confirmado en producción
• Rama hotfix/X.Y.Z creada desde main
• Corrección implementada y testeada
• Versión PATCH incrementada
• Merge a main + tag vX.Y.Z
• Merge a develop para sincronizar
• Rama hotfix/X.Y.Z eliminada