🚀 Flujo de desarrollo con Git

Este documento define el flujo de trabajo que el equipo debe seguir para integrar cambios en Git de forma ordenada, usando ramas de entorno (dev, qa, staging, main) y ramas temporales (feature/*, release/*, hotfix/*).

🌳 Ramas principales

main → Producción (deploy estable).
staging → Preproducción (validación antes de producción).
qa → Control de calidad (validación de features por sprint).
dev → Rama base para trabajo de desarrollo.
feature/*` → Ramas temporales para historias de usuario o bugfixes.
release/x.y.z → Ramas para preparar entregas de sprint.
hotfix/*` → Ramas para resolver bugs críticos en producción.

🔄 Flujo general

gitGraph
   commit id: "init"

   branch dev
   checkout dev
   commit id: "dev base"

   branch feature1
   commit id: "feat1 work"

   checkout dev
   branch feature2
   commit id: "feat2 work"

   checkout dev
   branch qa
   checkout qa
   merge feature1 id:"merge f1 -> qa"
   merge feature2 id:"merge f2 -> qa"

   checkout dev
   branch release1_0_0
   checkout release1_0_0
   merge feature1 id:"f1 aprobada"

   checkout dev
   branch staging
   checkout staging
   merge release1_0_0 id:"release -> staging"

   checkout main
   merge staging id:"staging -> main" tag:"v1.0.0"

📝 Pasos del flujo

1. Crear una feature branch

Se parte de dev:

git checkout dev
git pull origin dev
git checkout -b feature/nombre-feature

Convención de commits: Conventional Commits.

2. Integración en QA

Cuando la feature está lista:

git checkout qa
git pull origin qa
git merge feature/nombre-feature
git push origin qa

👉 QA valida la feature en el entorno correspondiente.

3. Si se aprueba en QA → merge a dev y release

Desde la misma feature branch:

# Integrar en dev
git checkout dev
git pull origin dev
git merge feature/nombre-feature
git push origin dev

# Integrar en release activa
git checkout release/1.2.0
git pull origin release/1.2.0
git merge feature/nombre-feature
git push origin release/1.2.0

⚠️ La feature/* se mantiene viva hasta que la release se publique en producción.

4. Integración en Staging

Cuando todas las features aprobadas del sprint están en release/x.y.z:

git checkout staging
git pull origin staging
git merge release/1.2.0
git push origin staging

5. Deploy a Producción (main)

Si staging es validado:

git checkout main
git pull origin main
git merge release/1.2.0

# Crear un tag de versión
git tag -a v1.2.0 -m "Release 1.2.0"
git push origin main --tags

6. Sincronización de ramas

Después de publicar:

# main se propaga hacia abajo
git checkout staging && git merge main && git push origin staging
git checkout dev && git merge staging && git push origin dev

👉 Así dev, staging y main quedan alineados.

7. Igualar QA con Dev (limpieza de sprint)

El objetivo: descartar de QA las features no aprobadas, pero mantenerlas en sus feature/*.

Opción recomendada (reset forzado):

git checkout qa
git fetch origin
git reset --hard origin/dev
git push origin qa --force

👉 QA queda idéntico a dev. 👉 Features rechazadas no se pierden porque siguen vivas en feature/*. 👉 En el siguiente sprint, esas features pueden volver a integrarse en QA.

📌 Ejemplo: Feature aprobada

Se crea la rama feature/login desde dev.
Se integra en qa.
QA la aprueba.
Se mergea en dev y en la rama release/x.y.z.
Cuando se libera la release, pasa a staging y luego a main.

sequenceDiagram
    participant Dev
    participant QA
    participant Release
    participant Staging
    participant Main

    Dev->>QA: PR feature/login → qa
    QA->>Dev: QA aprueba cambios
    QA->>Release: Merge feature/login en release/x.y.z
    QA->>Dev: Merge feature/login en dev
    Release->>Staging: Merge release/x.y.z
    Staging->>Main: Merge release/x.y.z + Tag v1.2.0

📌 Ejemplo: Feature rechazada en QA

Se crea feature/perfil desde dev.
Se integra en qa.
QA la rechaza → no pasa a release.
Al final del sprint, qa se resetea para igualarse con dev.
feature/perfil sigue viva y se corrige.
En el siguiente sprint se vuelve a integrar en qa.

sequenceDiagram
    participant Dev
    participant QA
    participant Feature

    Dev->>QA: PR feature/perfil → qa
    QA->>QA: QA detecta errores
    QA-->>Feature: Feature sigue en su rama
    Note over QA: Al final del sprint
qa se iguala con dev
    Feature->>QA: Corrección en feature/perfil
Se reintegra en qa
(siguiente sprint)

🔄 Flujo de Features con dependencias

Caso base (sin dependencias)

Partir siempre de dev:

git checkout dev
git pull origin dev
git checkout -b feature/login-screen-HU1234

Caso con dependencias (ft2 depende de ft1)

Si ft1 aún no está en release, pero ya pasó QA y el dev necesita seguir con ft2:

Se parte de ft1:

git checkout feature/login-screen-HU1234
 # Asegurarse que está actualizada con dev
git pull origin feature/login-screen-HU1234
git checkout -b feature/password-reset-HU1235

Cuando ft1 finalmente se integre en release, se hace merge normal y después ft2 puede ser mergeada también (ya no dependerá directamente de ft1 porque ambos terminarán en dev y release).

👉 Con esto se mantiene la continuidad sin bloquear el trabajo.

📝 Reglas para dependencias entre features

Una feature dependiente nunca debe mergearse directo a dev antes que la base.
- Ejemplo: ft2 no puede ir a dev si ft1 no está ahí todavía.
QA puede validar features encadenadas
- En qa se pueden integrar ft1 y ft2 juntas para probar el flujo completo.
En release solo entran las aprobadas
- Si ft1 se aprueba pero ft2 falla, ft1 entra en release y ft2 se queda viva en su rama.

📌 Ejemplo práctico

Escenario:

feature/login-screen-HU1234 (ft1) terminada → validada en QA.
feature/password-reset-HU1235 (ft2) depende de ft1.

Flujo:

ft1 creada desde dev.
ft2 creada desde ft1.
Ambas integradas a qa.
QA aprueba ft1, pero rechaza ft2.
Al final del sprint:
- ft1 se integra en release/1_2_0.
- ft2 sigue en su rama, se corrige y se reintenta el próximo sprint.

📊 Diagrama de dependencias

gitGraph
   commit id: "init"
   branch dev
   checkout dev
   commit id: "dev base"

   branch feature1_HU1234
   commit id: "ft1 work"

   checkout feature1_HU1234
   branch feature2_HU1235
   commit id: "ft2 work (depende de ft1)"

   checkout dev
   branch qa
   checkout qa
   merge feature1_HU1234 id:"ft1 -> qa"
   merge feature2_HU1235 id:"ft2 -> qa"

   checkout dev
   branch release1_2_0
   checkout release1_2_0
   merge feature1_HU1234 id:"ft1 aprobada"

   checkout dev
   branch staging
   checkout staging
   merge release1_2_0 id:"release -> staging"

   checkout main
   merge staging id:"staging -> main" tag:"v1.2.0"

🔥 Hotfix en Producción

Crear rama desde main:

git checkout main
git pull origin main
git checkout -b hotfix/bug-critico

Resolver bug y hacer commit.
PR hacia main, mergear y generar tag:

git checkout main
git merge hotfix/bug-critico
git tag -a v1.2.1 -m "Hotfix: bug crítico"
git push origin main --tags

Propagar cambios hacia abajo:

git checkout staging && git merge main && git push origin staging
git checkout dev && git merge staging && git push origin dev
git checkout qa && git reset --hard origin/dev && git push origin qa --force

📌 Ejemplo: Hotfix en Producción

Se detecta bug crítico en producción (main).
Se crea hotfix/pago-bug desde main.
Se corrige y se integra en main.
Se genera un nuevo tag (v1.2.1).
El hotfix se propaga hacia staging, dev y qa (qa se reinicia).

sequenceDiagram
participant Main
participant Hotfix
participant Staging
participant Dev
participant QA

    Main->>Hotfix: Crear hotfix/pago-bug desde main
    Hotfix->>Main: Merge hotfix/pago-bug → main
    Main->>Main: Crear tag v1.2.1
    Main->>Staging: Merge main → staging
    Staging->>Dev: Merge staging → dev
    Dev->>QA: QA se iguala con dev (reset)

⚙️ Manejo de archivos de configuración (.env, docker)

Los archivos .env y configuraciones de Docker no deben mezclarse entre ramas. Estrategias recomendadas:

Ignorar en Git
```
.env
docker-compose.override.yml
```
Cada ambiente mantiene sus propios archivos.
Usar plantillas versionadas Versionar .env.example con las variables necesarias. Cada desarrollador/servidor crea su .env local.
CI/CD con variables de entorno Configurar en el pipeline las variables (GITHUB_ACTIONS, GitLab CI, Jenkins, etc.) según la rama.

📛 Naming convention

Features:

feature/<nombre-descriptivo>-HU0000

Ejemplo:

feature/login-screen-HU1234
feature/payment-flow-HU5678

Hotfixes:

hotfix/<nombre-descriptivo>-PB0000

Ejemplo:

hotfix/fix-nullpointer-login-PB1234

Releases:
Terminal window
```
release/x_y_z
```
Ejemplo:
Terminal window
```
release/1_2_0
```

✅ Resumen de reglas

Todas las integraciones se hacen mediante PRs (nunca merge directo a main/staging/dev).
Naming convention estándar con feature/name-HU0000.
QA es un ambiente temporal que se reinicia cada sprint.
Features rechazadas se mantienen en sus ramas feature/*.
Dependencias gestionadas encadenando features (ft2 parte de ft1).
QA prueba features dependientes juntas pero en release se filtra solo lo aprobado.
Al limpiar QA al final del sprint, las dependientes no aprobadas siguen vivas en sus feature branches y se pueden reintentar.
Release branches se mantienen vivas y acumulan solo features aprobadas.
Hotfixes se crean desde main y se propagan hacia abajo.
Archivos de entorno (.env, docker configs) no deben mergearse, se gestionan por ambiente.

🎯 Con este flujo:

QA siempre empieza limpio cada sprint.→ solo lo aprobado pasa a release.
Features rechazadas no bloquean el release.→ siguen vivas en sus ramas.
Las release son acumulativas y persistentes.→ acumulan solo features aprobadas.
La sincronización mantiene todo alineado después de cada entrega.
Hotfixes se crean desde main y se propagan hacia abajo.
Archivos de entorno (.env, Docker configs) nunca se mergean, se gestionan por ambiente.