Documento de Estrategia de Branching en Git

Overview

Cada equipo que usa Git sin una estrategia de branching documentada eventualmente crea caos. Los desarrolladores crean ramas desde el lugar equivocado, los hotfixes evaden revision, los tags de release son inconsistentes, y revertir se convierte en un juego de adivinanzas. Un documento de estrategia de branching define como tu equipo usa Git: de donde vienen las ramas, como se mergean, quien puede aprobar, y como ocurren los releases.

When to Use

• For alternatives, see Engineering Handbook Template.

Usa este documento cuando:

• Tu equipo tiene mas de dos desarrolladores commiteando al mismo repositorio
• Necesitas soportar multiples releases concurrentes o entornos
• Los hotfixes frecuentemente entran en conflicto con desarrollo en curso
• Los nuevos miembros del equipo luchan por entender como contribuir
• Tu pipeline de CI/CD requiere patrones de branch especificos para disparar despliegues

Prerequisites

Antes de definir la estrategia:

• Entender tu cadencia de release (continuo, diario, semanal, por milestone)
• Conocer tus entornos de despliegue y como el codigo llega a ellos
• Decidir si necesitas soportar multiples versiones de produccion simultaneamente
• Confirmar que tu sistema de CI/CD puede disparar en patrones de branch o tags
• Alinear con producto sobre expectativas de rollback y tiempo de respuesta para hotfixes

Solution

# Estrategia de Branching Git: `<Proyecto/Equipo>`

> Version: ______ | Ultima actualizacion: ______ | Responsable: ______

## 1. Tipos de Ramas

### Ramas Principales

| Rama | Proposito | Proteccion | Duracion |
|------|-----------|------------|----------|
| `main` | Codigo listo para produccion | Requiere PR + 2 aprobaciones + CI verde | Permanente |
| `staging` | Validacion pre-produccion | Requiere PR + 1 aprobacion + CI verde | Permanente |
| `develop` | Rama de integracion para features | Requiere PR + 1 aprobacion + CI verde | Permanente |

### Ramas de Soporte

| Prefijo | Proposito | Fuente | Merge Target | Nomenclatura |
|---------|---------|--------|--------------|--------------|
| `feature/` | Nueva funcionalidad | `develop` | `develop` | `feature/TICKET-descripcion-corta` |
| `bugfix/` | Fixes no urgentes | `develop` | `develop` | `bugfix/TICKET-descripcion-corta` |
| `hotfix/` | Fixes criticos de produccion | `main` | `main` + `develop` | `hotfix/TICKET-descripcion-corta` |
| `release/` | Preparacion de release | `develop` | `main` + `staging` | `release/v1.2.3` |
| `chore/` | Mantenimiento, dependencias | `develop` | `develop` | `chore/TICKET-descripcion-corta` |
| `docs/` | Solo documentacion | `develop` | `develop` | `docs/TICKET-descripcion-corta` |

## 2. Flujo de Trabajo

### Desarrollo de Features

```bash
git checkout develop && git pull origin develop
git checkout -b feature/PROJ-123-add-user-auth
git push origin feature/PROJ-123-add-user-auth
## abrir PR a develop

Flujo de Hotfix

git checkout main && git pull origin main
git checkout -b hotfix/PROJ-456-fix-payment-webhook
## fix, test, commit
git push origin hotfix/PROJ-456-fix-payment-webhook
## PR a main (revision expeditada)
## despues del merge, backport a develop
git checkout develop && git cherry-pick <hotfix-commit>

Flujo de Release

git checkout develop && git pull origin develop
git checkout -b release/v1.2.3
## version bump, changelog, QA final
git checkout staging && git merge --no-ff release/v1.2.3
git checkout main && git merge --no-ff release/v1.2.3
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3
git checkout develop && git merge --no-ff main

3. Convenciones de Commits

Seguimos Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Tipos

Tipo	Uso Para	Dispara Release
feat	Nueva funcionalidad	Minor
fix	Bug fix	Patch
docs	Solo documentacion	Ninguno
style	Formateo	Ninguno
refactor	Cambio sin cambio de comportamiento	Ninguno
perf	Mejora de rendimiento	Patch
test	Tests	Ninguno
chore	Proceso, dependencias	Ninguno
ci	CI/CD	Ninguno
revert	Revertir commit previo	Patch

Ejemplos

feat(auth): add Google OAuth2 login

Implements OAuth2 flow with PKCE for web clients.
Closes PROJ-123

fix(payments): validate webhook signature

Prevents replay attacks by verifying Stripe signature
header before processing events.
Closes PROJ-456

4. Requisitos de Merge

Requisitos de Pull Request

Requisito	Feature/Bugfix	Hotfix	Release
CI pasa	Requerido	Requerido	Requerido
Aprobaciones de review	2	1 (expeditado)	2
Ticket enlazado	Requerido	Requerido	Requerido
Tests agregados	Requerido	Requerido	N/A
Documentacion actualizada	Si cambia funcionalidad	Si cambia comportamiento	Changelog actualizado
Revision de seguridad	Si auth/datos	Requerido	N/A

Estrategias de Merge

Rama Target	Estrategia	Razonamiento
develop	Squash and merge	Historial limpio; un commit por feature
main	Merge commit	Preserva historial de release
hotfix a main	Merge commit	Preserva identificacion del hotfix

5. Tagging y Versionado

Seguimos Semantic Versioning:

• MAJOR: Cambios breaking en API
• MINOR: Nuevas capacidades, backward compatible
• PATCH: Bug fixes, backward compatible

Formato de Tag

git tag -a v1.2.3 -m "Release v1.2.3"
git tag -a v1.2.3-rc.1 -m "Release candidate 1"
git tag -a v1.2.4 -m "Hotfix: fix payment webhook validation"

Reglas de Bump de Version

Tipo de Commit	Bump de Version
feat	Minor (x.Y.z)
fix, perf, revert	Patch (x.y.Z)
feat con BREAKING CHANGE	Major (X.y.z)
docs, style, refactor, test, chore, ci	Ninguno

6. Procedimientos de Rollback

Revertir un Despliegue

git log --oneline --decorate --tags
git checkout v1.2.2
git checkout -b hotfix/rollback-v1.2.3
git push origin hotfix/rollback-v1.2.3
## abrir PR de emergencia a main

Revertir un Merge

git log --oneline --merges
git revert -m 1 <merge-commit-hash>
## abrir PR con commit de revert

7. Reglas de Proteccion

Branch Protection (GitHub/GitLab)

Regla	main	staging	develop
Requerir PR	Si	Si	Si
Aprobaciones requeridas	2	1	1
Desechar aprobaciones stale	Si	Si	No
Requerir status checks	Si	Si	Si
Incluir administradores	Si	Si	No
Requerir historial lineal	No	No	Si
Permitir force push	No	No	No
Permitir borrados	No	No	No

## Explanation

El documento separa la estrategia de branching en **tipos de ramas** (como se llaman y para que sirven), **flujo de trabajo** (como crearlas y mergearlas), **convenciones de commits** (como describir cambios), y **reglas de proteccion** (como prevenir accidentes). El principio clave es que cada rama tiene exactamente un proposito y exactamente un target de merge. La ambiguedad sobre de donde vienen las ramas y a donde van crea los conflictos de merge y errores de despliegue que ralentizan a los equipos.

## Ejemplo de Flujo de Hotfix

```bash
# 1. Crear rama de hotfix desde main
git checkout main
git pull origin main
git checkout -b hotfix/fix-payment-webhook-validation

# 2. Hacer el fix
git add src/payments/webhook.go
git commit -m "fix(payments): validate webhook signature

Prevents replay attacks by verifying Stripe signature
header before processing events.
Closes PROJ-456"

# 3. Push y abrir PR a main (expeditado)
git push origin hotfix/fix-payment-webhook-validation
# Crear PR con label "hotfix" para revision expeditada

# 4. Despues de merge a main, tag el hotfix
git checkout main
git pull origin main
git tag -a v1.2.4 -m "Hotfix: fix payment webhook validation"
git push origin v1.2.4

# 5. Backport a develop
git checkout develop
git pull origin develop
git merge --no-ff main
git push origin develop

Variants

Estrategia	Mejor Para	Trade-off
GitFlow (como arriba)	Releases programados, multiples versiones	Mas ramas, mas proceso
GitHub Flow (main + feature)	Despliegue continuo, version unica	Mas simple, pero sin staging de release
Trunk-based (solo main)	CD de alta velocidad, feature flags	Requiere CI/CD maduro y feature flags
Release branching (por version)	Productos con versiones LTS	Mas overhead de backporting

Lo que funciona

1. Automatiza la proteccion — reglas de branch protection y CI checks atrapan errores antes del merge
2. Mantene ramas de corta vida — ramas de feature mayores a una semana crean riesgo de integracion
3. Tag cada release — los tags son la unica forma confiable de identificar lo que esta en produccion
4. Requiere links a tickets — commits sin contexto son inutiles para postmortems
5. Documenta excepciones — si alguien evade el proceso, documenta por que y si fue la decision correcta

Common Mistakes

1. Permitir push directo a main — incluso ingenieros senior cometen errores; branch protection es innegociable
2. No hacer backport de hotfixes a develop — el mismo bug se despliega en el siguiente release
3. Nomenclatura inconsistente de ramas — dificulta la automatizacion y el escaneo humano
4. Squash-merging hotfixes — pierde la habilidad de cherry-pickar o identificar el commit del fix
5. No borrar ramas mergeadas — el desorden dificulta encontrar trabajo activo

Troubleshooting

• Pipeline fails silently: enable verbose logging and store pipeline artifacts between stages so you can inspect the exact state that failed.
• Container crashes on startup: check that environment variables, secrets, and config files are mounted correctly. Read the first 50 lines of logs before scaling replicas.
• Deployment rolls back repeatedly: verify health checks, resource limits, and startup probes. A failing readiness probe is a common cause of rolling restarts.
• Slow CI builds: cache dependencies and docker layers. Split large test suites into parallel jobs to reduce wall-clock time.
• Drift between environments: use infrastructure-as-code and immutable artifacts.