🌳 BRANCHING PHILOSOPHY¶
Las Ramas como Narrativas Paralelas del Código¶
"Una rama no es solo una bifurcación técnica del código, es una decisión de explorar una realidad alternativa donde diferentes ideas pueden coexistir hasta que la mejor narrativa emerja."
📖 TABLA DE CONTENIDOS¶
- Metafísica de las Ramas
- Taxonomía de Estrategias
- Naming como Sistema Semántico
- Merge vs Rebase - Filosofías Opuestas
- Estrategia AudioLab
- Patrones Avanzados
- Anti-Patrones
- Casos de Estudio
🎭 CAPÍTULO 1: METAFÍSICA DE LAS RAMAS¶
El Concepto Central: Universos Paralelos¶
Imagina el código como un universo en expansión. Cada rama es una línea temporal alternativa donde diferentes decisiones se toman, diferentes experimentos se ejecutan, diferentes futuros se exploran.
🌍 MAIN (Reality Prime - La Línea Temporal Canónica)
│
│ t₀ - El Momento de la Decisión
│
┌────────┼────────┐
│ │
▼ ▼
🌍 Reality A 🌍 Reality B
(feature-X) (feature-Y)
│ │
│ │
│ │
"¿Qué pasaría "¿Qué pasaría
si añadimos si refactorizamos
reverb AI?" el motor DSP?"
│ │
│ │
▼ ▼
Experimentación Experimentación
Desarrollo Desarrollo
Testing Testing
│ │
│ │
└─────── ⚡ ──────┘
│
▼
🌍 CONVERGENCIA
(Ambas realidades
colapsan en una)
Las Cuatro Preguntas Existenciales¶
🔹 Pregunta 1: ¿Cuándo una realidad merece su propia rama?¶
NO necesitas una rama cuando: - Es un cambio de 1 línea (typo, comment fix) - Es 100% seguro y no experimental - No hay posibilidad de conflicto - Se completa en < 10 minutos
SÍ necesitas una rama cuando:
1. Cambio > 1 commit¶
Umbral de complejidad alcanzado
│
├─ Modificación afecta > 3 archivos
├─ Requiere múltiples pasos lógicos
├─ Necesita commits intermedios descriptivos
└─ Puede tomar > 1 hora
2. Experimentación incierta¶
No sabes si funcionará
│
├─ Pruebas de concepto
├─ Algoritmos experimentales
├─ Nuevas arquitecturas
└─ Refactorings mayores
3. Desarrollo paralelo necesario¶
Múltiples personas trabajando
│
├─ Feature compartido entre devs
├─ Depende de otro trabajo en progreso
├─ Necesita code review extenso
└─ Integración gradual requerida
4. Aislamiento de riesgo¶
Puede romper cosas
│
├─ Cambios en sistema crítico
├─ Refactoring profundo
├─ Actualizaciones de dependencias
└─ Cambios de arquitectura
🔹 Pregunta 2: ¿Cuándo múltiples realidades colapsan en una?¶
CRITERIOS DE CONVERGENCIA:
┌─────────────────────────────────────────────────────┐
│ EXPERIMENTO EXITOSO │
│ ✅ Tests pasan │
│ ✅ Code review aprobado │
│ ✅ No rompe funcionalidad existente │
│ ✅ Performance aceptable │
└─────────────────────────────────────────────────────┘
│
▼
🌍 MERGE TO MAIN
┌─────────────────────────────────────────────────────┐
│ FEATURE COMPLETA │
│ ✅ Todos los criterios de aceptación cumplidos │
│ ✅ Documentación actualizada │
│ ✅ Tests de integración pasan │
│ ✅ No hay deuda técnica significativa │
└─────────────────────────────────────────────────────┘
│
▼
🌍 MERGE TO DEVELOP
┌─────────────────────────────────────────────────────┐
│ DECISIÓN TOMADA │
│ ✅ Stakeholders aprobaron │
│ ✅ Arquitectura validada │
│ ✅ Path forward claro │
│ ✅ Resources committed │
└─────────────────────────────────────────────────────┘
│
▼
🌍 COMMIT TO DIRECTION
┌─────────────────────────────────────────────────────┐
│ CONSENSO ALCANZADO │
│ ✅ Team alignment │
│ ✅ Mejor solución identificada │
│ ✅ Trade-offs aceptados │
│ ✅ Timeline acordado │
└─────────────────────────────────────────────────────┘
│
▼
🌍 INTEGRATE
🔹 Pregunta 3: ¿Cuándo una realidad muere sin fusionarse?¶
ESCENARIOS DE ABANDONO:
💀 EXPERIMENTO FALLIDO
│
├─ Performance inaceptable
├─ Complejidad > Beneficio
├─ Approach fundamentalmente erróneo
└─ Mejor alternativa encontrada
│
└─► DELETE BRANCH
(pero documentar aprendizajes)
💀 CAMBIO DE DIRECCIÓN
│
├─ Producto pivotea
├─ Prioridades cambian
├─ Feature cancelada
└─ Resource constraints
│
└─► ARCHIVE & DOCUMENT
(puede ser útil futuro)
💀 MERGE IMPOSSIBLE
│
├─ Conflictos irreconciliables
├─ Base ha cambiado radicalmente
├─ Obsoleto por otros cambios
└─ Demasiado divergente
│
└─► RECREATE FROM SCRATCH
(si aún es necesario)
🔹 Pregunta 4: ¿Cuántas realidades pueden coexistir simultáneamente?¶
LÍMITES COGNITIVOS Y PRÁCTICOS:
🧠 LÍMITE INDIVIDUAL
│
├─ 1 persona = máx 2-3 branches activas
├─ Más = context switching overhead
├─ Calidad degradada con > 3
└─ Recomendación: 1 feature a la vez
👥 LÍMITE DE EQUIPO
│
├─ Team pequeño (2-5) = máx 5-8 branches
├─ Team mediano (6-15) = máx 10-15 branches
├─ Team grande (16+) = límite depende de estructura
└─ Recomendación: branches = 1.5 × devs activos
🏗️ LÍMITE DE REPOSITORIO
│
├─ < 20 branches activas = saludable
├─ 20-50 branches = necesita cleanup
├─ > 50 branches = caos organizacional
└─ Recomendación: cleanup semanal
La Naturaleza Temporal de las Ramas¶
┌──────────────────────────────────────────────────────┐
│ CICLO DE VIDA DE UNA RAMA │
└──────────────────────────────────────────────────────┘
╭──────╮
│BIRTH │ Momento de creación
╰──┬───╯ "git branch feature-X"
│
├──► 🌱 INFANCIA (horas-días)
│ Primeros commits exploratorios
│ Estructura emergiendo
│ Dirección tomando forma
│
├──► 🌿 ADOLESCENCIA (días-semana)
│ Desarrollo activo
│ Tests añadiéndose
│ Refactoring iterativo
│
├──► 🌲 MADUREZ (semana-2 semanas)
│ Feature completa
│ Estable y testeada
│ Lista para integración
│
├──► ⚡ INTEGRACIÓN
│ Merge/rebase a parent
│ Conflictos resueltos
│ CI passing
│
└──► 💀 MUERTE
Branch eliminada
Vive en historia de main
Propósito cumplido
┌──────────────────────────────────────────────────────┐
│ TIEMPO DE VIDA RECOMENDADO │
├──────────────────────────────────────────────────────┤
│ Hotfix: < 4 horas │
│ Bug fix: < 2 días │
│ Feature: < 1 semana │
│ Epic: < 2 semanas (subdivide más) │
│ Experiment: < 1 mes (luego decide) │
│ Release: ~ 1 sprint │
└──────────────────────────────────────────────────────┘
La Geometría del Branching¶
Las ramas no son solo líneas - son formas geométricas con propiedades:
LONGITUD (Divergencia Temporal)¶
SHORT BRANCH (Preferible)
main: A──B──C──────D
│╲ ╱
│ E──F
LONG BRANCH (Riesgoso)
main: A──B──C──D──E──F──G──H──I
│╲ ╱
│ J─K─L─M─N─O─P
Problemas:
├─ Conflictos acumulados
├─ Context drift
├─ Integration hell
└─ Review imposible
ANCHO (Número de cambios)¶
NARROW BRANCH (Focused)
files changed: 3-5
lines changed: 50-200
commits: 3-8
WIDE BRANCH (Sprawling)
files changed: 20+
lines changed: 1000+
commits: 30+
Solución: DIVIDE
├─ Subdivide en sub-features
├─ Stage la integración
├─ Incremental merges
└─ Feature flags
PROFUNDIDAD (Branches de branches)¶
FLAT (Simple)
main
├─ feature-A
├─ feature-B
└─ feature-C
NESTED (Complejo)
main
└─ develop
├─ feature-A
│ ├─ sub-feature-A1
│ └─ sub-feature-A2
└─ feature-B
└─ experiment-B1
Usar nesting solo cuando:
├─ Absolutamente necesario
├─ Bien documentado
├─ Team experimentado
└─ Clear integration path
🏗️ CAPÍTULO 2: TAXONOMÍA DE ESTRATEGIAS¶
Comparación Visual de Modelos Principales¶
🔷 MODELO 1: GIT FLOW (Formal y Ceremonioso)¶
🌍 MAIN (production-ready)
│
├──────●────────●────────●──── RELEASES
│ │ │ │
│ v1.0.0 v1.1.0 v2.0.0
│ │ │ │
│ │ │ │
🔀 DEVELOP (integration heaven)
│╲ ╱│╲ ╱│╲ ╱│
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲ │ ╲╱ │ ╲╱ │
🌱 🌱 🔥 🌱🌱 🔥 🌱🌱
features hotfix features hotfix
FLUJO DETALLADO:
1. FEATURE DEVELOPMENT
develop ──► feature/X ──► develop
2. RELEASE PREPARATION
develop ──► release/X.Y ──► main + develop
3. HOTFIX CRITICAL
main ──► hotfix/X ──► main + develop
4. VERSION TAGGING
main: tag v1.0.0 after merge
CARACTERÍSTICAS COMPLETAS¶
┌─────────────────────────────────────────────────────────┐
│ 🎯 DISCIPLINA ████████░░ 9/10│
│ 🚀 VELOCIDAD █████░░░░░ 5/10│
│ 🎭 CEREMONIAL ██████████ 10/10│
│ 📏 OVERHEAD █████████░ 9/10│
│ 🎪 TEAM SIZE ÓPTIMO Large (10+) │
│ 🧠 CURVA DE APRENDIZAJE Alta │
│ 🔧 COMPLEJIDAD MANTENIMIENTO Alta │
│ 📊 VISIBILIDAD HISTORIA Excelente │
└─────────────────────────────────────────────────────────┘
FILOSOFÍA CORE¶
"Múltiples capas de validación antes de llegar a realidad. Cada paso es un checkpoint. Nada llega a producción sin pasar por el proceso completo."
PRINCIPIOS: - Separación absoluta: develop nunca es production - Release branches: preparación aislada - Hotfix path: bypass controlado para emergencias - Tag everything: versioning explícito
CUÁNDO USAR¶
✅ IDEAL PARA:
├─ Releases programados (v1.0, v2.0 schedule)
├─ Múltiples versiones en producción simultáneas
├─ Proceso de QA formal y extenso
├─ Regulaciones estrictas (medical, finance, aerospace)
├─ Deployment windows específicos
├─ Large teams con roles especializados
└─ Software empaquetado (no SaaS)
❌ EVITAR CUANDO:
├─ Continuous deployment es goal
├─ Small team (< 5 devs)
├─ Fast iteration necesaria
├─ Overhead > beneficio
└─ Simplicidad es prioridad
VARIANTES Y ADAPTACIONES¶
GIT FLOW LITE
main ──► develop ──► features
(sin release branches si no son necesarias)
GIT FLOW EXTENDED
main ──► develop ──► staging ──► features
(ambiente intermedio para validación)
🔷 MODELO 2: GITHUB FLOW (Simple y Directo)¶
🌍 MAIN (always deployable - la única verdad)
│╲ ╱│╲ ╱│╲ ╱│
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
🌱 feature 🌱 feature 🌱 feature
(short) (short) (short)
FLUJO ULTRA-SIMPLE:
1. Branch from main
main ──► feature/X
2. Develop + Push regularly
Commits pequeños y frecuentes
3. Pull Request cuando listo
Code review + CI
4. Merge to main
Deploy immediately (o pronto)
5. Delete branch
Cleanup inmediato
CARACTERÍSTICAS COMPLETAS¶
┌─────────────────────────────────────────────────────────┐
│ 🎯 DISCIPLINA ██████░░░░ 6/10│
│ 🚀 VELOCIDAD █████████░ 9/10│
│ 🎭 CEREMONIAL ██░░░░░░░░ 2/10│
│ 📏 OVERHEAD ██░░░░░░░░ 2/10│
│ 🎪 TEAM SIZE ÓPTIMO Small-Med (2-10)│
│ 🧠 CURVA DE APRENDIZAJE Baja │
│ 🔧 COMPLEJIDAD MANTENIMIENTO Baja │
│ 📊 VISIBILIDAD HISTORIA Buena │
└─────────────────────────────────────────────────────────┘
FILOSOFÍA CORE¶
"Main siempre deployable. Features cortas y frecuentes. Ship fast, ship often. La simplicidad es una virtud. El mejor código es el que está en producción."
PRINCIPIOS: - Single source of truth: solo main importa - Deploy early, deploy often: integración continua - Small batches: features pequeñas y manejables - Fast feedback: CI/CD crítico
REGLAS DE ORO¶
┌─────────────────────────────────────────────────────────┐
│ REGLA 1: Main siempre deployable │
│ ├─ CI/CD must pass antes de merge │
│ ├─ Tests comprehensivos requeridos │
│ ├─ Code review obligatorio │
│ └─ Rollback plan siempre disponible │
│ │
│ REGLA 2: Branch cortas (< 2-3 días) │
│ ├─ Reduce merge conflicts │
│ ├─ Facilita code review │
│ ├─ Faster feedback loop │
│ └─ Less context switching │
│ │
│ REGLA 3: Deploy fast after merge │
│ ├─ Automated deployment preferible │
│ ├─ Monitoring crítico │
│ ├─ Rollback automatizado │
│ └─ Feature flags para gradual rollout │
│ │
│ REGLA 4: Pull Requests son documentación │
│ ├─ Describe el "por qué" │
│ ├─ Screenshots/videos si UI │
│ ├─ Testing notes │
│ └─ Deployment considerations │
└─────────────────────────────────────────────────────────┘
CUÁNDO USAR¶
✅ IDEAL PARA:
├─ SaaS products (continuous deployment)
├─ Web applications
├─ Small to medium teams
├─ Fast iteration cycles
├─ Startups y high-growth companies
├─ Microservices architecture
└─ Cloud-native applications
❌ EVITAR CUANDO:
├─ Múltiples versiones en producción
├─ Deployment windows restrictivos
├─ Proceso QA manual extenso
├─ Regulación estricta requiere staging
└─ Releases coordinados cross-team
HERRAMIENTAS COMPLEMENTARIAS¶
ESENCIALES:
├─ CI/CD pipeline robusto
├─ Automated testing (unit + integration)
├─ Feature flags system
├─ Monitoring & alerting
├─ Rollback automation
└─ Code review tools
OPCIONALES PERO ÚTILES:
├─ A/B testing framework
├─ Canary deployment
├─ Blue-green deployment
└─ Smoke tests automatizados
🔷 MODELO 3: TRUNK-BASED (Extremadamente Simple)¶
🌍 TRUNK (la única rama que importa)
│●─●─●─●─●─●─●─●─●─●─●─●─●─●─●─●
│▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲ ▲
││ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
Commits directos mayormente
Branches opcionales (< 1 día):
│╲╱│╲╱│╲╱│
│ ● │ ● │ ● (micro-branches)
│ │ │
(merge same day)
FLUJO MINIMALISTA:
1. Commit directamente a trunk (si es pequeño)
O
2. Branch muy corta (< 1 día)
trunk ──► temp ──► trunk
3. Feature flags para WIP features
⚑ Flag ON: nueva feature visible
⚑ Flag OFF: feature hidden
4. Continuous integration cada commit
CI passing = auto-deploy
CARACTERÍSTICAS COMPLETAS¶
┌─────────────────────────────────────────────────────────┐
│ 🎯 DISCIPLINA ██████████ 10/10│
│ 🚀 VELOCIDAD ██████████ 10/10│
│ 🎭 CEREMONIAL █░░░░░░░░░ 1/10│
│ 📏 OVERHEAD █░░░░░░░░░ 1/10│
│ 🎪 TEAM SIZE ÓPTIMO Maduro (expert)│
│ 🧠 CURVA DE APRENDIZAJE Muy Alta │
│ 🔧 COMPLEJIDAD MANTENIMIENTO Baja │
│ 📊 VISIBILIDAD HISTORIA Linear/Perfect│
└─────────────────────────────────────────────────────────┘
FILOSOFÍA CORE¶
"Integrate continuously, release fearlessly. Feature flags control visibility, no branches. La rama ES el código. Uno con el trunk. Máxima velocidad, máxima disciplina."
PRINCIPIOS FUNDAMENTALES:
🔹 INTEGRACIÓN CONTINUA EXTREMA
├─ Commit a trunk mínimo diario
├─ Preferiblemente múltiples por día
├─ CI debe completar en < 10 minutos
└─ Build roto = prioridad absoluta
🔹 FEATURE FLAGS COMO ARQUITECTURA
├─ Código incompleto puede ir a trunk
├─ Features se activan cuando están listas
├─ A/B testing built-in
└─ Rollback instantáneo (flip flag)
🔹 PEQUEÑOS CAMBIOS INCREMENTALES
├─ Cada commit es un paso completo
├─ "Strangler pattern" para refactors
├─ Never break trunk
└─ Always deployable
🔹 CONFIANZA EN TESTING
├─ Test coverage > 80%
├─ Fast test suite (< 10 min)
├─ Tests son specification
└─ TDD preferred
PRE-REQUISITOS CRÍTICOS¶
❗ NO INTENTES TRUNK-BASED SIN:
┌─────────────────────────────────────────────────────────┐
│ ✅ CI/CD completamente automatizado │
│ └─ Build, test, deploy sin intervención humana │
│ │
│ ✅ Test suite comprehensivo y RÁPIDO │
│ └─ Coverage > 80%, execution < 10 min │
│ │
│ ✅ Feature flags infrastructure │
│ └─ Ability to toggle features runtime │
│ │
│ ✅ Monitoring & observability robusto │
│ └─ Detectar problemas en segundos │
│ │
│ ✅ Team maduro y disciplinado │
│ └─ Entienden y respetan el proceso │
│ │
│ ✅ Rollback automatizado │
│ └─ Revert en < 5 minutos │
└─────────────────────────────────────────────────────────┘
CUÁNDO USAR¶
✅ IDEAL PARA:
├─ Equipos maduros con cultura DevOps fuerte
├─ Continuous deployment maestría
├─ Microservices con deployment independiente
├─ High-frequency deployment (múltiples por día)
├─ Monorepos con CI incremental
├─ Google/Facebook/Netflix-style development
└─ Teams que viven y respiran automation
❌ EVITAR CUANDO:
├─ Team nuevo o junior
├─ CI/CD no está sólido
├─ No hay feature flag infrastructure
├─ Testing coverage bajo
├─ Deployment manual o lento
├─ Miedo a romper cosas
└─ Cultura de blame
FEATURE FLAGS EN PRÁCTICA¶
// Código en trunk, feature hidden
if (FeatureFlags.isEnabled("new-reverb-algorithm")) {
return newReverbAlgorithm();
} else {
return legacyReverbAlgorithm();
}
VENTAJAS:
├─ Deploy código no terminado safely
├─ Gradual rollout (10% → 50% → 100%)
├─ A/B testing integrado
├─ Instant rollback (flip flag)
└─ No merge hell
DESVENTAJAS:
├─ Technical debt (cleanup flags)
├─ Testing complexity (2ⁿ combinations)
├─ Infrastructure overhead
└─ Requires discipline
🔷 MODELO 4: GITLAB FLOW (Environment-Driven)¶
🌱 feature branches
│╲
│ ╲
▼ ╲
🌍 MAIN (source of truth)
│ ╲
│ ╲
▼ ╲
🔵 STAGING (pre-production)
│ ╲
│ ╲
▼ ╲
🟢 PRODUCTION (stable release)
│
▼
📦 DEPLOYED
FLUJO ORIENTADO A AMBIENTES:
1. Develop en feature branch
feature/X → commits
2. Merge a MAIN cuando listo
feature/X → main
3. Main auto-deploy a STAGING
main → staging environment
4. QA valida en staging
Manual/automated testing
5. Promote a PRODUCTION
staging → production (cherry-pick o merge)
6. Hotfixes pueden bypass
hotfix → main → staging → production
(con fast-track)
CARACTERÍSTICAS COMPLETAS¶
┌─────────────────────────────────────────────────────────┐
│ 🎯 DISCIPLINA ████████░░ 8/10│
│ 🚀 VELOCIDAD ██████░░░░ 6/10│
│ 🎭 CEREMONIAL ██████░░░░ 6/10│
│ 📏 OVERHEAD ██████░░░░ 6/10│
│ 🎪 TEAM SIZE ÓPTIMO Medium (5-20) │
│ 🧠 CURVA DE APRENDIZAJE Media │
│ 🔧 COMPLEJIDAD MANTENIMIENTO Media │
│ 📊 VISIBILIDAD HISTORIA Muy Buena │
└─────────────────────────────────────────────────────────┘
FILOSOFÍA CORE¶
"Environment promotion pipeline es el flujo natural. Código fluye como agua de mountain a ocean: feature → main → staging → production. Cada ambiente es un checkpoint."
VARIANTES SEGÚN NECESIDAD¶
VARIANT 1: Simple (2 ambientes)
feature → main → production
VARIANT 2: Standard (3 ambientes)
feature → main → staging → production
VARIANT 3: Extended (4+ ambientes)
feature → main → dev → staging → pre-prod → production
VARIANT 4: Multi-deployment
┌─► production-US
main → staging ├─► production-EU
└─► production-ASIA
CUÁNDO USAR¶
✅ IDEAL PARA:
├─ Múltiples ambientes de deployment
├─ QA manual/automated en staging
├─ Gradual rollout por región
├─ Compliance requiere staging validation
├─ Deployment windows (change management)
├─ Enterprise environments
└─ SaaS con multiple deployment tiers
❌ EVITAR CUANDO:
├─ Solo hay production (no staging)
├─ Continuous deployment directo a prod
├─ Small team sin recursos para múltiples environments
└─ Overhead > beneficio
ENVIRONMENT BRANCHING PATTERNS¶
PATTERN A: Auto-promotion
main ──auto──► staging ──manual──► production
PATTERN B: Manual gates
main ──PR──► staging ──approval+PR──► production
PATTERN C: Tag-based
main (tag v1.0) ──► staging ──► production
📊 MATRIZ COMPARATIVA COMPLETA¶
╔═══════════════════════════════════════════════════════════════════════════════╗
║ FEATURE COMPARISON MATRIX ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ CARACTERÍSTICA │ Git Flow │GitHub Flow│Trunk-Based│GitLab Flow│ ║
║ ──────────────────┼──────────┼───────────┼───────────┼───────────┤ ║
║ Simplicidad │ ★★ │ ★★★★★ │ ★★★★ │ ★★★ │ ║
║ Velocidad │ ★★ │ ★★★★★ │ ★★★★★ │ ★★★★ │ ║
║ Control │ ★★★★★ │ ★★★ │ ★★ │ ★★★★ │ ║
║ Scalability │ ★★★★★ │ ★★★ │ ★★★★ │ ★★★★ │ ║
║ Learning Curve │ ★★★★★ │ ★★ │ ★★★★★ │ ★★★ │ ║
║ CI/CD Friendly │ ★★ │ ★★★★ │ ★★★★★ │ ★★★★ │ ║
║ Release Control │ ★★★★★ │ ★★ │ ★★ │ ★★★★ │ ║
║ Hotfix Speed │ ★★★★ │ ★★★★★ │ ★★★★★ │ ★★★★ │ ║
║ History Clean │ ★★★ │ ★★★ │ ★★★★★ │ ★★★ │ ║
║ Multi-version │ ★★★★★ │ ★ │ ★ │ ★★★ │ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
🎨 CAPÍTULO 3: NAMING COMO SISTEMA SEMÁNTICO¶
El Poder del Naming¶
Un nombre de rama no es solo una etiqueta - es comunicación, documentación, intención codificada. Un buen sistema de naming permite:
- Entender el propósito sin leer código
- Filtrar y buscar branches efectivamente
- Automation basada en patterns
- Team coordination sin reuniones
Anatomía de un Branch Name¶
┌─────────────────────────────────────────────────────────┐
│ ESTRUCTURA SEMÁNTICA │
└─────────────────────────────────────────────────────────┘
type / scope / description - issue
──── ───── ────────── ─────
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
feature / dsp / reverb-algorithm - 142
┌──┴──┐ ┌─┴─┐ ┌─────┴──────┐ ┌┴┐
│TYPE │ │SCOPE│ │DESCRIPTION │ │#│
└─────┘ └─────┘ └────────────┘ └─┘
QUÉ DÓNDE POR QUÉ REF
Taxonomía de Branch Types¶
╔═══════════════════════════════════════════════════════════════════════════╗
║ TYPE │ EJEMPLO │ SIGNIFICA │ LIFETIME ║
╠═══════════════════════════════════════════════════════════════════════════╣
║ ║
║ feature/ │ feature/reverb-dsp │ Nueva capability │ 2-7 días ║
║ │ feature/ai-mixing │ Additive change │ ║
║ │ │ │ ║
║ fix/ │ fix/clicks-on-stop │ Bug repair │ 1-3 días ║
║ │ fix/memory-leak-vst3 │ Correctivo │ ║
║ │ │ │ ║
║ hotfix/ │ hotfix/crash-startup │ Prod emergency │ < 1 día ║
║ │ hotfix/security-cve │ Urgente crítico │ ║
║ │ │ │ ║
║ release/ │ release/v1.2.0 │ Release prep │ 3-7 días ║
║ │ release/v2.0.0-beta │ Stabilización │ ║
║ │ │ │ ║
║ experiment/ │ experiment/ml-audio │ Research spike │ 1-4 sem ║
║ │ experiment/webgpu │ Proof-of-concept │ ║
║ │ │ │ ║
║ refactor/ │ refactor/dsp-core │ Internal improve │ 3-7 días ║
║ │ refactor/memory-pool │ No new features │ ║
║ │ │ │ ║
║ docs/ │ docs/api-reference │ Documentation │ 1-3 días ║
║ │ docs/architecture │ Pure docs │ ║
║ │ │ │ ║
║ test/ │ test/stress-testing │ Test improvement │ 2-5 días ║
║ │ test/integration-suite │ Validation │ ║
║ │ │ │ ║
║ perf/ │ perf/simd-optimization │ Performance │ 3-7 días ║
║ │ perf/reduce-latency │ Speed/efficiency │ ║
║ │ │ │ ║
║ chore/ │ chore/dependency-update│ Maintenance │ 1-2 días ║
║ │ chore/ci-improvements │ Tooling/process │ ║
║ │ │ │ ║
╚═══════════════════════════════════════════════════════════════════════════╝
Principios de Naming Excellence¶
🔹 PRINCIPIO 1: Jerárquico y Organizado¶
SIN JERARQUÍA (Caos):
├─ reverb-feature
├─ fix-the-bug
├─ new-eq
├─ johns-experiment
└─ temporary-branch
CON JERARQUÍA (Orden):
├─ feature/
│ ├─ feature/dsp/reverb-algorithm
│ ├─ feature/ui/new-eq-panel
│ └─ feature/audio/pitch-correction
├─ fix/
│ ├─ fix/dsp/clicks-on-stop
│ └─ fix/ui/knob-sensitivity
├─ experiment/
│ └─ experiment/ml/audio-generation
└─ refactor/
└─ refactor/core/memory-management
BENEFICIOS:
├─ Git GUI tools agrupan automáticamente
├─ Búsqueda más fácil
├─ Automation basada en prefix
└─ Mental model claro
🔹 PRINCIPIO 2: Descriptivo y Auto-documentado¶
❌ MAL (Vago y genérico):
├─ fix
├─ new-feature
├─ update
├─ temp
└─ test-branch
✅ BIEN (Específico y claro):
├─ fix/audio/remove-dc-offset-distortion
├─ feature/effects/vintage-tape-saturation
├─ refactor/dsp/extract-filter-coefficients
├─ experiment/performance/lockfree-ringbuffer
└─ test/integration/vst3-host-compatibility
REGLA:
Alguien que vea el nombre debe entender:
├─ QUÉ se está cambiando
├─ POR QUÉ se está cambiando
└─ DÓNDE está el cambio
🔹 PRINCIPIO 3: Incluir Referencias¶
CON ISSUE TRACKER:
feature/142-reverb-algorithm
fix/275-memory-leak-on-close
hotfix/301-crash-vst3-scan
SIN ISSUE TRACKER:
feature/reverb-algorithm
fix/memory-leak-on-close
hotfix/crash-vst3-scan
BENEFICIOS DE REFERENCIAS:
├─ Link automático en PR
├─ Trazabilidad completa
├─ Context en issue tracker
└─ Metrics y reporting
FORMATO:
type/issue-description
type/scope/issue-description
type/issue-scope-description
🔹 PRINCIPIO 4: Consistencia de Equipo¶
ESTABLECER CONVENCIÓN DEL EQUIPO:
┌─────────────────────────────────────────────────────────┐
│ AUDIOLAB NAMING CONVENTION │
├─────────────────────────────────────────────────────────┤
│ │
│ FORMAT: │
│ type/scope/short-description-with-dashes │
│ │
│ TYPES (obligatorio): │
│ feature, fix, hotfix, release, │
│ experiment, refactor, docs, test, perf, chore │
│ │
│ SCOPE (opcional pero recomendado): │
│ dsp, ui, audio, plugin, core, build, ci │
│ │
│ DESCRIPTION: │
│ - lowercase │
│ - dashes not underscores │
│ - descriptive not vague │
│ - < 50 characters │
│ │
│ EJEMPLOS: │
│ ✅ feature/dsp/reverb-algorithm │
│ ✅ fix/audio/buffer-underrun │
│ ✅ experiment/ml/audio-classification │
│ ❌ new_feature │
│ ❌ johns-branch │
│ ❌ temp │
└─────────────────────────────────────────────────────────┘
Naming Anti-Patterns¶
🚫 ANTI-PATTERN 1: Nombres personales
├─ johns-branch
├─ marys-experiment
└─ temp-alex
PROBLEMA: No comunica contenido
SOLUCIÓN: Nombrar por contenido, no persona
🚫 ANTI-PATTERN 2: Temporal genérico
├─ temp
├─ test
├─ tmp-branch
└─ asdf
PROBLEMA: Olvidado y abandonado
SOLUCIÓN: Nombre específico o DELETE
🚫 ANTI-PATTERN 3: Demasiado largo
└─ feature/add-new-reverb-algorithm-with-improved-performance-and-better-ui-controls
PROBLEMA: Difícil de trabajar
SOLUCIÓN: < 50 chars, specificity vs brevity balance
🚫 ANTI-PATTERN 4: Números sin contexto
├─ branch1
├─ branch2
└─ version3
PROBLEMA: Sin significado
SOLUCIÓN: Nombre descriptivo
🚫 ANTI-PATTERN 5: Mezcla de convenciones
├─ feature/reverb
├─ FEATURE-EQ
├─ new_compressor
└─ Fix/Limiter
PROBLEMA: Inconsistencia confunde
SOLUCIÓN: Enforce convención
Automation Basada en Naming¶
EJEMPLO: CI/CD Pipelines
# PR naming determina flujo
feature/* → run full test suite
fix/* → run regression tests
hotfix/* → fast-track + notify
experiment/* → optional CI
docs/* → skip tests, build docs
test/* → run extended tests
# Auto-labeling en PRs
feature/* → label: "enhancement"
fix/* → label: "bug"
docs/* → label: "documentation"
# Deployment routing
release/* → deploy to staging
hotfix/* → deploy to production
🔀 CAPÍTULO 4: MERGE VS REBASE - FILOSOFÍAS OPUESTAS¶
El Gran Debate Filosófico¶
Esta no es solo una discusión técnica - es una pregunta sobre la naturaleza de la historia y la verdad.
┌──────────────────────────────────────────────────────────┐
│ DOS FILOSOFÍAS IRRECONCILIABLES │
├──────────────────────────────────────────────────────────┤
│ │
│ MERGE CAMP: │
│ "La historia debe preservarse exactamente como sucedió │
│ con toda su complejidad y verdad." │
│ │
│ REBASE CAMP: │
│ "La historia debe contarse de manera clara y linear, │
│ optimizada para comprensión futura." │
│ │
└──────────────────────────────────────────────────────────┘
🔷 FILOSOFÍA MERGE: Historia Verdadera¶
Mecánica Visual¶
ANTES DEL MERGE:
main: A──B──C
╲
╲
feature: D──E
SITUACIÓN:
├─ Main ha avanzado (B→C)
├─ Feature ha avanzado (A→D→E)
├─ Ambas histories son válidas
└─ Necesitan converger
DESPUÉS DEL MERGE:
main: A──B──C────F ← Merge commit
╲ ╱ │
╲ ╱ │
feature: D──E │
│
Historia
preservada
Anatomía del Merge Commit¶
commit f3d9a1c (merge commit)
Merge: c8f4b2a e7d3c9b
Author: Developer
Date: ...
Merge branch 'feature/reverb' into main
Brings in:
- New reverb algorithm
- Performance optimizations
- Updated tests
┌─────────────────────────────────┐
│ Parents: [c8f4b2a, e7d3c9b] │
│ ├─ main parent │
│ └─ feature parent │
│ │
│ Represents: convergence │
│ Contains: conflict resolution │
└─────────────────────────────────┘
Argumentos A Favor¶
📜 VERDAD HISTÓRICA
├─ Muestra exactamente cuándo y cómo se desarrolló
├─ Paralelismo visible
├─ Context de desarrollo preservado
└─ "Esto ES lo que pasó"
BENEFICIO: Forensics detallado
EJEMPLO: "¿Por qué esta decisión se tomó?"
→ Puedes ver el branch completo
🔗 COMMITS AGRUPADOS
├─ Feature commits permanecen juntos
├─ Fácil ver "qué vino de dónde"
├─ Git log --graph muestra estructura
└─ Logical units preserved
BENEFICIO: Code review post-merge
EJEMPLO: "¿Qué cambios trajo feature-X?"
→ Mira entre merge commit parents
👥 COLABORACIÓN VISIBLE
├─ Múltiples desarrolladores visibles
├─ Branches de larga duración manejables
├─ Conflicts resolution documentada
└─ Team dynamics capturados
BENEFICIO: Team awareness
EJEMPLO: Ver quién trabajó en qué parallel
⏮️ REVERSIÓN ELEGANTE
├─ Revert merge commit revierte todo
├─ Single operation
├─ Safe rollback
└─ Historia no se pierde
BENEFICIO: Risk management
EJEMPLO: git revert -m 1 <merge-commit>
→ Todo el feature se va
Argumentos En Contra¶
🌳 GRAFO COMPLEJO
├─ Historia no-linear
├─ Difícil seguir flujo
├─ Git log confuso
└─ Visualización requiere tools
PROBLEMA: Cognitive load
EJEMPLO:
* f3d9a1c Merge branch X
|\
| * e7d3c9b Feature commit 3
| * d6c2b8a Feature commit 2
* | c8f4b2a Main commit
|/
* b7a1c9d ...
🔍 BÚSQUEDA DIFÍCIL
├─ Git bisect complicado
├─ Blame menos útil
├─ Log linear no existe
└─ Context switching mental
PROBLEMA: Debugging overhead
EJEMPLO: Buscar "cuándo se introdujo bug"
→ Bisect atraviesa merges
📊 "RUIDO" DE MERGE COMMITS
├─ Commits sin código
├─ Solo metadata
├─ Inflan historia
└─ Diluyen signal
PROBLEMA: Signal-to-noise
EJEMPLO: 50% de commits son merges
→ Historia menos legible
🔷 FILOSOFÍA REBASE: Historia Limpia¶
Mecánica Visual¶
ANTES DEL REBASE:
main: A──B──C
╲
╲
feature: D──E
DESPUÉS DEL REBASE:
main: A──B──C──D'──E'
↑ ↑
│ │
Reescritos on top of C
La rama feature ahora aparece como si
hubiera sido creada desde C, no desde A.
El Proceso de Rewrite¶
PASO A PASO:
1. Git identifica commits únicos de feature
Commits: D, E
2. Temporalmente los "guarda"
Stash: [D, E]
3. Mueve feature pointer a main
feature → C (mismo que main)
4. Re-aplica commits uno por uno
C → apply D → D' (nuevo commit, nuevo hash)
D' → apply E → E' (nuevo commit, nuevo hash)
5. Feature ahora apunta a E'
Historia reescrita
CRÍTICO: D y E ya NO EXISTEN
D' y E' son NUEVOS commits
(diferentes hashes, mismos cambios)
Argumentos A Favor¶
📏 HISTORIA LINEAR
├─ Simple línea recta
├─ Fácil de seguir
├─ git log clean
└─ No zigzag mental
BENEFICIO: Claridad cognitiva
EJEMPLO:
A──B──C──D'──E'──F──G──H
↑
Cada commit en orden
Historia como libro
📖 LECTURA SIMPLE
├─ Commits en orden lógico
├─ Cada commit hace sentido solo
├─ No context switching
└─ Newcomers pueden entender
BENEFICIO: Onboarding
EJEMPLO: New dev lee historia
→ Secuencia lógica clara
🎯 CADA COMMIT EN CONTEXTO ACTUAL
├─ D' es D pero sobre C (no sobre A)
├─ Conflicts resueltos una vez
├─ Tests corren sobre código actual
└─ No "surprise" integrations
BENEFICIO: Quality
EJEMPLO: Cada commit testeado contra main actual
🔍 GIT BISECT EFECTIVO
├─ Binary search linear
├─ Cada paso claro
├─ No merges complicando
└─ Bug finding rápido
BENEFICIO: Debugging
EJEMPLO: Bisect con 100 commits
→ 7 steps vs 15 con merges
Argumentos En Contra¶
📜 HISTORIA REESCRITA (no es "verdad")
├─ Commits nuevos (hashes diferentes)
├─ Timestamps engañosos
├─ "Mentira útil" vs verdad
└─ Forensics limitado
PROBLEMA: Authenticity loss
EJEMPLO: "¿Cuándo realmente se escribió D?"
→ Timestamp de D' es más reciente
⚠️ PELIGROSO EN BRANCHES COMPARTIDAS
├─ Reescribe historia pública
├─ Otros devs tienen old commits
├─ Force push requerido
└─ Potential data loss
PROBLEMA: Coordination
EJEMPLO: 2 devs en mismo branch
→ Rebase causa divergence
🔄 CONFLICTOS PUEDEN REPETIRSE
├─ Cada commit puede conflict
├─ Mismo conflict n veces
├─ Tedioso con largo feature
└─ Rebase can abort
PROBLEMA: Overhead
EJEMPLO: Feature con 10 commits
main con 50 commits nuevos
→ Potential 10 × conflict resolution
🎭 PÉRDIDA DE CONTEXTO
├─ Branch structure perdida
├─ Parallel work invisible
├─ Collaboration history lost
└─ "¿Quién trabajó cuándo?"
PROBLEMA: Team visibility
EJEMPLO: No puedes ver
"feature se desarrolló en paralelo"
La Regla de Oro¶
┌──────────────────────────────────────────────────────────┐
│ ⚠️ LA REGLA DE ORO DEL REBASE ⚠️ │
├──────────────────────────────────────────────────────────┤
│ │
│ NUNCA rebase commits que has pushed a remote │
│ y que OTROS están usando. │
│ │
│ ✅ SAFE: Rebase tu branch local privado │
│ ✅ SAFE: Rebase tu feature branch (solo tú) │
│ ❌ DANGER: Rebase main │
│ ❌ DANGER: Rebase shared feature branch │
│ │
└──────────────────────────────────────────────────────────┘
Estrategia Híbrida (Best of Both Worlds)¶
🎯 ESTRATEGIA RECOMENDADA:
REBASE para trabajo local:
├─ Mantén tu feature branch limpio
├─ Rebase sobre main regularmente
├─ Squash commits WIP
└─ Historia linear en tu feature
MERGE para integración:
├─ Merge feature → main
├─ Preserva feature como unit
├─ Historia de colaboración visible
└─ Fácil revert si necesario
VISUAL:
Tu feature branch (local):
main: A──B──────────C──────────D
╲ ╲
rebase ╲ ╲
daily ╲ ╲
E'─F'─G' H'─I'─J'
↑
(rebased again)
Integration final:
main: A──B──C──D────────K (merge commit)
╱
feature: H'─I'─J'───╯
(clean history)
(but preserved as unit)
Decision Tree¶
┌─────────────────┐
│ Necesito integrar│
│ cambios? │
└────────┬─────────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────┐ ┌─────────┐
│ Local? │ │ Shared? │
│ (solo yo)│ │ (team) │
└────┬────┘ └────┬────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ REBASE │ │ MERGE │
│ │ │ │
│ ✅ Clean │ │ ✅ Safe │
│ ✅ Linear│ │ ✅ True │
│ ✅ Simple│ │ ✅ Revert│
└──────────┘ └──────────┘
🎯 CAPÍTULO 5: ESTRATEGIA AUDIOLAB (RECOMENDACIÓN)¶
Overview: Hybrid Approach¶
Para AudioLab, recomendamos una estrategia híbrida inspirada en Git Flow + GitHub Flow, adaptada para desarrollo de audio:
🌍 MAIN (production-ready, always buildable)
│
│────────────● v1.0.0 ──────● v1.1.0 ──────● v2.0.0
│ │ │ │
│ (tags en releases)
│ │ │ │
🔀 DEVELOP (integration, staging ground)
│╲ ╱│╲ ╱│╲ ╱│╲ ╱│
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
│ ╲╱ │ ╲ │ ╲ │ ╲ │
🌱 🌱 🧪 🌱 🔧 🌱 🌱 🧪 🌱
feat fix exp ref fix feat exp feat
LAYERS:
├─ MAIN: Truth, production
├─ DEVELOP: Integration playground
├─ FEATURES: Short-lived work branches
└─ EXPERIMENTS: Research branches (longer lived)
Branch Categories for AudioLab¶
╔═══════════════════════════════════════════════════════════════╗
║ BRANCH TYPE │ LIFETIME │ FROM │ TO │ STRATEGY ║
╠═══════════════════════════════════════════════════════════════╣
║ ║
║ feature/* │ < 1 week │ develop │ develop │ Squash ║
║ fix/* │ < 3 days │ develop │ develop │ Squash ║
║ experiment/* │ < 1 month │ develop │ develop │ Merge ║
║ refactor/* │ < 1 week │ develop │ develop │ Squash ║
║ perf/* │ < 1 week │ develop │ develop │ Squash ║
║ release/* │ ~ 1 sprint│ develop │ main │ Merge ║
║ hotfix/* │ < 1 day │ main │ main+dev│ Merge ║
║ ║
╚═══════════════════════════════════════════════════════════════╝
Naming Convention¶
┌──────────────────────────────────────────────────────────┐
│ AUDIOLAB BRANCH NAMING STANDARD │
├──────────────────────────────────────────────────────────┤
│ │
│ FORMAT: │
│ type/scope/description │
│ type/description (si scope no aplica) │
│ │
│ TYPES (required): │
│ feature - Nueva funcionalidad │
│ fix - Bug fix │
│ hotfix - Production emergency │
│ experiment - Research/POC │
│ refactor - Code improvement │
│ perf - Performance optimization │
│ test - Test improvements │
│ docs - Documentation │
│ release - Release preparation │
│ │
│ SCOPES (optional pero recomendado): │
│ dsp - DSP algorithms │
│ audio - Audio engine │
│ plugin - Plugin framework │
│ ui - User interface │
│ core - Core systems │
│ build - Build system │
│ ci - CI/CD │
│ │
│ DESCRIPTION: │
│ - lowercase-with-dashes │
│ - descriptive not generic │
│ - 2-5 words ideal │
│ - < 50 characters │
│ │
│ EJEMPLOS VÁLIDOS: │
│ ✅ feature/dsp/reverb-algorithm │
│ ✅ fix/audio/buffer-underrun-startup │
│ ✅ experiment/ml/audio-source-separation │
│ ✅ refactor/core/memory-pool-allocation │
│ ✅ hotfix/plugin/vst3-crash-on-close │
│ ✅ perf/dsp/simd-vectorization │
│ │
│ EJEMPLOS INVÁLIDOS: │
│ ❌ new-feature │
│ ❌ johns-work │
│ ❌ temp │
│ ❌ fix-bug │
│ ❌ FEATURE-REVERB │
│ │
└──────────────────────────────────────────────────────────┘
Lifetime Policies¶
⏰ BRANCH LIFETIME LIMITS
┌────────────────────────────────────────────────────┐
│ TIPO │ MAX LIFETIME │ ACCIÓN │
├────────────────────────────────────────────────────┤
│ feature/* │ 7 días │ Merge o subdivide │
│ fix/* │ 3 días │ Merge urgente │
│ hotfix/* │ 1 día │ Merge inmediato │
│ experiment/* │ 30 días │ Decide o archive │
│ refactor/* │ 7 días │ Merge o revert │
│ release/* │ 14 días │ Release o abort │
└────────────────────────────────────────────────────┘
ENFORCEMENT:
├─ CI warning si > 50% lifetime
├─ CI fail si > 100% lifetime
├─ Automated stale branch detection
└─ Weekly cleanup review
Merge Strategies¶
🔀 MERGE STRATEGY POR TIPO
FEATURE → DEVELOP: Squash Merge
├─ Historia interna no importante
├─ 1 commit limpio en develop
├─ Mensaje descriptivo completo
└─ fácil revert
EJEMPLO:
feature/dsp/reverb (15 commits)
↓ squash
develop: "Add reverb algorithm with Schroeder model"
──────────────────────────────────────────────────────
EXPERIMENT → DEVELOP: Merge Commit
├─ Historia importante (research journey)
├─ Preservar commits
├─ Contexto de desarrollo
└─ Puede revertir como unit
EJEMPLO:
experiment/ml/source-separation (40 commits)
↓ merge
develop: preserva historia de experimento
──────────────────────────────────────────────────────
DEVELOP → MAIN: Merge Commit
├─ Grupo de features
├─ Release marker
├─ Important milestone
└─ Easy revert
EJEMPLO:
develop (50 commits desde último merge)
↓ merge
main: "Release v1.2.0"
──────────────────────────────────────────────────────
HOTFIX → MAIN: Direct Merge
├─ Fast-track
├─ Bypass develop
├─ Luego cherry-pick a develop
└─ Urgent fix
EJEMPLO:
hotfix/crash ──► main
└──► develop (cherry-pick)
Protection Rules¶
🛡️ BRANCH PROTECTION
MAIN:
├─ ❌ No direct commits
├─ ✅ Require pull request
├─ ✅ Require 1+ approvals
├─ ✅ Require CI passing
├─ ✅ Require up-to-date with base
├─ ✅ Include administrators
└─ ✅ Allow only merge commits
DEVELOP:
├─ ❌ No direct commits (except hotfix backport)
├─ ✅ Require pull request
├─ ✅ Require CI passing
├─ ⚠️ No approval required (but recommended)
└─ ✅ Allow squash and merge commits
FEATURE BRANCHES:
├─ ✅ Direct commits OK
├─ ⚠️ Rebase permitido (private branches)
└─ ⚠️ Force push OK (con cuidado)
Workflow Ejemplos¶
FEATURE WORKFLOW¶
1. CREATE BRANCH
develop ──► feature/dsp/reverb-algorithm
2. DEVELOP LOCALLY
├─ Commit frecuentemente
├─ Push para backup
└─ Rebase sobre develop si diverge
3. READY FOR REVIEW
├─ Rebase interactivo para limpiar
├─ Tests locales passing
└─ Create PR
4. CODE REVIEW
├─ Address comments
├─ Push fixes
└─ CI must pass
5. MERGE
├─ Squash merge a develop
├─ Delete feature branch
└─ Close any linked issues
HOTFIX WORKFLOW¶
1. DISCOVER CRITICAL BUG (en producción)
2. CREATE HOTFIX BRANCH
main ──► hotfix/crash-on-startup
3. FIX ASAP
├─ Minimal change
├─ Tests que reproduzcan bug
└─ Tests passing
4. FAST-TRACK PR
├─ Target: main
├─ Urgent review
└─ CI must pass
5. MERGE TO MAIN
├─ Merge commit
├─ Tag version (v1.1.1)
└─ Deploy immediately
6. BACKPORT TO DEVELOP
├─ Cherry-pick hotfix commit
├─ O merge hotfix branch
└─ Keep develop in sync
EXPERIMENT WORKFLOW¶
1. HYPOTHESIS
"ML puede mejorar audio quality"
2. CREATE LONG-LIVED BRANCH
develop ──► experiment/ml/audio-enhancement
3. RESEARCH PHASE (varias semanas)
├─ Múltiples approachs
├─ Dead ends OK
├─ Document findings
└─ Periodic rebases sobre develop
4. DECISION POINT (~ 1 mes)
┌─ ✅ Éxito ─► Merge a develop (preserve history)
│
├─ ⚠️ Promising ─► Continue (extend deadline)
│
└─ ❌ Failure ─► Archive (no delete, documentar)
5. SI MERGE:
├─ Merge commit (no squash)
├─ Preserve research journey
└─ Document in merge message
RELEASE WORKFLOW¶
1. PREPARE RELEASE
develop ──► release/v1.2.0
2. STABILIZATION (1-2 weeks)
├─ No new features
├─ Bug fixes only
├─ Version bumps
├─ Changelog updates
└─ Documentation finalization
3. TESTING PHASE
├─ Regression testing
├─ Performance testing
├─ Cross-platform validation
└─ User acceptance (beta)
4. RELEASE
├─ Merge to main
├─ Tag version
├─ Merge back to develop
└─ Delete release branch
5. POST-RELEASE
├─ Deploy to production
├─ Announce release
├─ Monitor for issues
└─ Hotfix if needed
🚀 CAPÍTULO 6: PATRONES AVANZADOS DE BRANCHING¶
Pattern 1: Feature Flags + Trunk-Based (Hybrid)¶
Combina trunk-based discipline con safety de branches:
🌍 MAIN
│─F1─F2─F3─F4─F5─F6─F7─F8
│ │ │ │ │ │ │ │
⚑ ⚑ ⚑ ⚑ ⚑ ⚑ ⚑ ⚑
│ │ │ │ │ │ │ │
Features flags:
├─ reverb: OFF (WIP)
├─ eq-new: OFF (WIP)
├─ limiter: ON (complete)
└─ compressor: ON (complete)
VENTAJAS:
├─ Deploy código incompleto safely
├─ Fast integration
├─ A/B testing
└─ Gradual rollout
REQUIERE:
├─ Feature flag infrastructure
├─ Disciplina alta
└─ Test coverage excelente
Pattern 2: Parallel Development Tracks¶
Para features large que toman meses:
🌍 MAIN
│
🔀 DEVELOP
│
├─► 🎨 UI-REDESIGN (long-lived)
│ │
│ ├─► feature/ui/new-theme
│ ├─► feature/ui/responsive
│ └─► feature/ui/accessibility
│
└─► 🧠 DSP-V2 (long-lived)
│
├─► feature/dsp/new-engine
├─► feature/dsp/simd-opt
└─► experiment/dsp/ml-processing
REGLAS:
├─ Merge sub-features a track
├─ Merge track a develop cuando completo
├─ Mantener tracks sincronizados con develop
└─ Clear ownership por track
Pattern 3: Monorepo Multi-Component¶
Diferentes componentes, diferentes flujos:
audio-lab/
├─ core/ (stable, infrequent changes)
│ └─ release/1.x
│
├─ plugins/ (active development)
│ └─ develop
│ ├─ feature/reverb
│ └─ feature/eq
│
├─ ui/ (rapid iteration)
│ └─ main (trunk-based)
│
└─ docs/ (continuous)
└─ main
STRATEGY:
Cada componente tiene su strategy óptimo
Pattern 4: Release Trains¶
Releases programados, features se suben al "tren":
TIME: Week 1 Week 2 Week 3 Week 4
│ │ │ │
🚂─────►│ │ │ Train A (release 1.1)
🚂─────►│ │ Train B (release 1.2)
🚂─────►│ Train C (release 1.3)
🚂 Train D (release 1.4)
FEATURES:
├─ Feature X ready week 1 ─► Train A
├─ Feature Y ready week 2 ─► Train B
└─ Feature Z ready week 3 ─► Train C
VENTAJAS:
├─ Predictable releases
├─ Features no bloquean release
└─ Continuous delivery
Pattern 5: Stacked Diffs¶
Features que dependen entre sí:
main: A──B──C
╲
D──E (feature-1)
╲
F──G (feature-2, depende de feature-1)
╲
H──I (feature-3, depende de feature-2)
WORKFLOW:
1. PR1: D-E (feature-1)
2. PR2: F-G (feature-2, base=feature-1)
3. PR3: H-I (feature-3, base=feature-2)
MERGE ORDER:
PR1 → PR2 → PR3
VENTAJAS:
├─ Parallel review
├─ Logical subdivision
└─ Incremental integration
⚠️ CAPÍTULO 7: ANTI-PATRONES Y TRAMPAS COMUNES¶
Anti-Pattern 1: The Eternal Branch¶
❌ SÍNTOMA:
feature/big-refactor
Created: 6 months ago
Commits: 450
Files changed: 200+
Conflicts with main: Irreconcilable
PROBLEMA:
├─ Divergencia masiva
├─ Integration hell
├─ Code review imposible
└─ Risk altísimo
SOLUCIÓN:
├─ Never permitir > 2 semanas
├─ Subdivide en sub-features
├─ Incremental integration
└─ Considerar feature flags
Anti-Pattern 2: The Ghost Town¶
❌ SÍNTOMA:
git branch -a
feature/xyz (last commit: 18 months ago)
experiment/abc (last commit: 1 year ago)
temp-branch (last commit: 2 years ago)
... (50+ dead branches)
PROBLEMA:
├─ Clutter cognitivo
├─ Namespace pollution
├─ No sabes qué es activo
└─ Overhead de sync
SOLUCIÓN:
├─ Weekly cleanup ritual
├─ Delete merged branches auto
├─ Archive experiments
└─ Stale branch policy
Anti-Pattern 3: The Merge Cascade¶
❌ SÍNTOMA:
git log --graph
* Merge branch X
|\
| * Merge branch Y
| |\
| | * Merge branch Z
| | |\
| | | * Merge branch W
| | | |\
...
PROBLEMA:
├─ Merge commits of merge commits
├─ Historia ilegible
├─ Bisect imposible
└─ WTF graph
SOLUCIÓN:
├─ Rebase before merge
├─ Squash merge small features
├─ Linear history policy
└─ Prohibir merges de merges
Anti-Pattern 4: The Cowboy Commit¶
❌ SÍNTOMA:
git log main
* Fix (direct commit to main)
* WIP don't use (direct to main)
* Trying something (direct to main)
PROBLEMA:
├─ No review
├─ No CI check
├─ Breaking changes
└─ Bypassing process
SOLUCIÓN:
├─ Branch protection
├─ PR required always
├─ No exceptions (ni para admin)
└─ Post-mortem si sucede
Anti-Pattern 5: The Rebase Hell¶
❌ SÍNTOMA:
git rebase main
CONFLICT (100 conflicts)
git rebase --continue
CONFLICT (50 more conflicts)
git rebase --continue
CONFLICT (25 more...)
git rebase --abort
😭
PROBLEMA:
├─ Branch demasiado largo
├─ Main ha cambiado radicalmente
├─ Conflicts repetitivos
└─ Frustración
SOLUCIÓN:
├─ Rebase frecuentemente (daily)
├─ Keep branches short
├─ Consider merge instead
└─ Subdivide large changes
Anti-Pattern 6: The Ambiguous Name¶
❌ SÍNTOMA:
git branch
temp
new-feature
fix
johns-branch
test-123
asdf
PROBLEMA:
├─ Sin significado
├─ No sabes qué hay dentro
├─ No puedes buscar
└─ Olvidado inmediatamente
SOLUCIÓN:
├─ Naming convention estricta
├─ CI enforcement
├─ Descriptive names
└─ Reject bad names en PR
Anti-Pattern 7: The Force Push Disaster¶
❌ SÍNTOMA:
Developer A: git push --force
Developer B: git pull
fatal: refusing to merge unrelated histories
WTF happened to my commits?!
PROBLEMA:
├─ Historia reescrita en shared branch
├─ Otros devs pierden trabajo
├─ Commits huérfanos
└─ Team chaos
SOLUCIÓN:
├─ NUNCA force push shared branches
├─ --force-with-lease si necesario
├─ Comunicar antes de force push
└─ Protect important branches
📚 CAPÍTULO 8: CASOS DE ESTUDIO¶
Caso 1: Startup Pequeño (3 devs)¶
CONTEXTO:
├─ Team: 3 developers
├─ Product: Audio plugin (nueva startup)
├─ Deployment: Continuous a beta users
└─ Prioridad: Speed over process
STRATEGY ELEGIDA: GitHub Flow
🌍 MAIN (always deployable)
│╲ ╱│╲ ╱│╲ ╱│
│ ╲ ╱ │ ╲ ╱ │ ╲ ╱ │
🌱 feat 🌱 fix 🌱 feat
REGLAS:
├─ Branch from main
├─ PR required (1 approval)
├─ CI must pass
├─ Merge → deploy automático
└─ Branches < 2-3 días
RESULTADOS:
✅ Deploy 5-10x por semana
✅ Fast iteration
✅ Minimal overhead
✅ Team happy
LECCIONES:
├─ Simple funciona para teams pequeños
├─ Automation es crítico
└─ Disciplina suple proceso
Caso 2: Empresa Mediana (15 devs)¶
CONTEXTO:
├─ Team: 15 developers (3 squads)
├─ Product: DAW (Digital Audio Workstation)
├─ Deployment: Monthly releases
└─ Prioridad: Quality + Coordination
STRATEGY ELEGIDA: Git Flow Modificado
🌍 MAIN
│
🔀 DEVELOP
│╲ ╱│╲ ╱│
🌱🌱 🌱🌱
MODIFICACIONES:
├─ Release branches (2 week stabilization)
├─ Hotfix fast-track
├─ Squash merge features
└─ Automated testing extensivo
RESULTADOS:
✅ Releases predecibles
✅ Quality alta
✅ Coordination efectiva
⚠️ Slower que startups (OK para ellos)
LECCIONES:
├─ Process scaling necesario
├─ Trade-off speed vs quality
└─ Clear roles (release manager, etc)
Caso 3: Open Source (50+ contributors)¶
CONTEXTO:
├─ Team: 50+ occasional contributors
├─ Product: Audio library (open source)
├─ Deployment: Semantic versioning
└─ Prioridad: Stability + Community
STRATEGY ELEGIDA: Fork + PR Model
UPSTREAM:
🌍 MAIN
│
FORK (cada contributor):
🌍 main (synced)
│
🌱 feature
FLOW:
Fork → Branch → PR → Review → Merge
REGLAS:
├─ Fork obligatorio
├─ PR a main
├─ 2+ approvals required
├─ CI + manual QA
├─ Maintainers merge
└─ Semantic versioning estricto
RESULTADOS:
✅ Community contributions++
✅ Quality control
✅ Stable releases
⚠️ Slow (pero apropiado)
LECCIONES:
├─ Process protege calidad
├─ Maintainer workload alto
└─ Automation salva vidas
Caso 4: Enterprise (100+ devs)¶
CONTEXTO:
├─ Team: 100+ developers (20 teams)
├─ Product: Audio software suite
├─ Deployment: Quarterly + patches
└─ Prioridad: Compliance + Stability
STRATEGY ELEGIDA: Scaled Git Flow + Mono repo
🌍 MAIN
│
🔀 DEVELOP
│
├─► 🎨 UI-TRACK
│ ├─ team-ui-1
│ └─ team-ui-2
│
├─► 🧠 ENGINE-TRACK
│ ├─ team-engine-1
│ └─ team-engine-2
│
└─► 🔌 PLUGINS-TRACK
├─ team-plugins-1
└─ team-plugins-2
REGLAS:
├─ Team tracks (long-lived)
├─ Feature branches off tracks
├─ PR + 2 approvals
├─ Automated testing gates
├─ Release trains
└─ Compliance checkpoints
RESULTADOS:
✅ Scales a 100+ devs
✅ Parallel development
✅ Quality gates
⚠️ Complex (necesario)
⚠️ Tooling investment required
LECCIONES:
├─ Scaling needs structure
├─ Automation non-negotiable
├─ Process overhead aceptable
└─ Clear ownership critical
🎓 CONCLUSIÓN: Elegir Tu Camino¶
No hay "una estrategia correcta" - hay la estrategia correcta para ti:
┌──────────────────────────────────────────────────────────┐
│ DECISION FRAMEWORK │
├──────────────────────────────────────────────────────────┤
│ │
│ PREGÚNTATE: │
│ │
│ 1. ¿Cuántos developers activos? │
│ < 5 → Simple (GitHub Flow) │
│ 5-20 → Medium (GitLab Flow / Light Git Flow) │
│ 20+ → Complex (Git Flow / Scaled) │
│ │
│ 2. ¿Deployment frequency? │
│ Multiple/día → Trunk-based │
│ Few/semana → GitHub Flow │
│ Few/mes → Git Flow │
│ │
│ 3. ¿Nivel de team? │
│ Junior → Structure alta (Git Flow) │
│ Mixed → Medium (GitLab Flow) │
│ Senior → Low structure OK (Trunk) │
│ │
│ 4. ¿Riesgo de errores? │
│ Alto (medical, finance) → Git Flow │
│ Medio (enterprise) → GitLab Flow │
│ Bajo (startup) → GitHub Flow │
│ │
│ 5. ¿CI/CD maturity? │
│ Excelente → Trunk-based │
│ Bueno → GitHub Flow │
│ Básico → Git Flow │
│ │
└──────────────────────────────────────────────────────────┘
Las ramas son narrativas. Elige cómo quieres contar la historia de tu código.
📖 APÉNDICE: Quick Reference¶
╔═══════════════════════════════════════════════════════════╗
║ BRANCHING PHILOSOPHY CHEAT SHEET ║
╠═══════════════════════════════════════════════════════════╣
║ ║
║ CUÁNDO CREAR BRANCH: ║
║ ✅ Cambio > 1 commit ║
║ ✅ Experimentación ║
║ ✅ Trabajo paralelo ║
║ ✅ Aislamiento de riesgo ║
║ ║
║ CUÁNDO NO CREAR BRANCH: ║
║ ❌ Typo fix ║
║ ❌ Comment change ║
║ ❌ < 10 minutos trabajo ║
║ ║
║ NAMING: ║
║ ✅ type/scope/description ║
║ ✅ Descriptivo ║
║ ✅ Consistente ║
║ ❌ temp, test, john ║
║ ║
║ LIFETIME: ║
║ feature < 1 week ║
║ fix < 3 days ║
║ hotfix < 1 day ║
║ experiment < 1 month ║
║ ║
║ MERGE STRATEGY: ║
║ Squash → Features pequeñas ║
║ Merge → Features grandes, experiments ║
║ Rebase → Local cleanup ║
║ ║
║ REGLA DE ORO: ║
║ No rebase shared branches ║
║ ║
╚═══════════════════════════════════════════════════════════╝
Documento versión 1.0 AudioLab Foundation • Version Control • Branching Philosophy "Las ramas son realidades paralelas. Elige sabiamente qué realidades explorar."