05_17_00 - Version Strategy¶

Estrategia Global de Versionado de AudioLab¶

Estado: ✅ Implementado Versión: 1.0.0

📋 Descripción¶

Este subsistema implementa la filosofía de evolución controlada del código de AudioLab, definiendo cómo se numeran versiones, cuándo se incrementan, y cómo fluyen a través de su ciclo de vida desde desarrollo hasta end-of-life.

Filosofía¶

Version Strategy no son solo reglas de versionado; es la constitución del desarrollo de AudioLab, estableciendo las leyes fundamentales que todos los desarrolladores siguen para garantizar:

Predictibilidad - Los usuarios saben qué esperar de cada actualización
Compatibilidad - Código antiguo funciona con versiones nuevas cuando debe
Trazabilidad - Cada cambio tiene un número de versión único
Comunicación - Los números de versión comunican el tipo de cambios

🎯 Semantic Versioning¶

AudioLab usa Semantic Versioning 2.0 extendido con metadata adicional.

Formato¶

MAJOR.MINOR.PATCH-PRERELEASE+BUILD

Ejemplos: - 2.1.0 - Versión estable - 2.1.0-alpha.1 - Primera alpha de 2.1 - 2.1.0-beta.3 - Tercera beta de 2.1 - 2.1.0-rc.1 - Release candidate - 2.1.0+20250315.a5f3b2c - Con build metadata

Reglas de Incremento¶

MAJOR (Breaking Changes)¶

Incrementa cuando hay cambios incompatibles que requieren modificaciones en código de usuario:

✅ Cuándo incrementar: - Breaking API changes en interfaces públicas - Cambios incompatibles en formato de presets - Rediseño arquitectónico mayor - Plataformas eliminadas (e.g., dejar de soportar Windows 7) - Features deprecadas removidas - Cambios fundamentales en comportamiento DSP

Ejemplo: 1.5.8 → 2.0.0

MINOR (New Features)¶

Incrementa cuando se añaden nuevas características backward-compatible:

✅ Cuándo incrementar: - Nuevas features añadidas (compatible hacia atrás) - Nuevos módulos o engines introducidos - Mejoras significativas de performance (>20%) - Nuevas plataformas soportadas - Features deprecadas (aún funcionan con warnings) - Nuevos algoritmos DSP

Ejemplo: 2.0.3 → 2.1.0

PATCH (Bug Fixes)¶

Incrementa cuando se corrigen bugs sin cambios en API:

✅ Cuándo incrementar: - Bug fixes (sin cambios de API) - Performance tweaks (<20% mejora) - Actualizaciones solo de documentación - Parches de seguridad - Mejoras en build system - Actualizaciones de dependencias (nivel patch)

Ejemplo: 2.1.0 → 2.1.1

🔄 Lifecycle Phases¶

Cada versión pasa por un ciclo de vida definido:

Development → Alpha → Beta → RC → Stable → (LTS) → EOL

1. Development (dev)¶

Version: 2.1.0-dev
Stability: None
API Changes: Frequent
Support: None

Características: - Código activo en rama develop - Sin garantías de estabilidad - Cambios frecuentes y breaking changes permitidos - Solo para desarrollo interno

2. Alpha¶

Version: 2.1.0-alpha.1
Duration: 2-4 weeks
Stability: Unstable
API Changes: Allowed
Support: Community only

Características: - Testing temprano, bugs esperados - API mostly stable pero cambios posibles - Distribución a early adopters - Tests básicos pasando (>80% coverage)

Exit Criteria: - Todas las features planificadas implementadas - Bugs mayores corregidos - API razonablemente estable

3. Beta¶

Version: 2.1.0-beta.3
Duration: 4-6 weeks
Stability: Mostly stable
API Changes: Minimal (critical only)
Support: Bug reports accepted

Características: - Feature complete, en fase de testing - API estable, solo cambios críticos - Performance optimizado - Documentación completa - Tests completos (>90% coverage)

Exit Criteria: - No critical bugs - Todos los tests pasando - Performance targets alcanzados - Documentación completa

4. Release Candidate (RC)¶

Version: 2.1.0-rc.1
Duration: 1-2 weeks
Stability: Stable
API Changes: None (critical bugs only)
Support: Full support

Características: - Calidad de producción - API locked, sin cambios - Fully optimized - Security audit pasado - Codesigning habilitado

Exit Criteria: - Zero critical bugs - Zero regressions conocidas - Todas las aprobaciones obtenidas - Legal review completo - Release notes finalizados

5. Stable¶

Version: 2.1.0
Duration: Until next MINOR or 1 year
Stability: Production ready
API Changes: None (additions only in MINOR)
Support: Full support

Características: - Listo para producción - API locked (solo adiciones en MINOR updates) - Performance completamente optimizado - Soporte completo (24-48h response) - Todas las plataformas testeadas

6. LTS (Long-Term Support)¶

Version: 2.1.0 (LTS)
Duration: 2-3 years
Stability: Rock solid
API Changes: Security only
Support: Extended support

Características: - Versión probada en producción (6+ meses) - Gran base de usuarios - Importancia estratégica - Solo security patches y critical bugs - Soporte extendido garantizado

7. EOL (End of Life)¶

Version: 2.1.0 (EOL)
Notice: 6 months advance
Stability: Frozen
Support: None

Características: - Sin actualizaciones - Sin soporte - Código archivado - Migration path documentado - 6 meses de aviso previo

🔧 Versionado por Componente¶

AudioLab usa versionado independiente para diferentes niveles:

Core¶

Version: Main version (e.g., 2.1.0)
Description: Framework principal de AudioLab
Compatibility: Defines compatibility for all components

Kernels (L0)¶

Version: Inherits from Core
Description: DSP kernels de bajo nivel
Compatibility: Must match Core MAJOR.MINOR exactly
Example: Core 2.1.0 → Kernels 2.1.x

Atoms (L1)¶

Version: Independent patch versions
Description: Unidades DSP atómicas
Compatibility: Must match Core MAJOR, MINOR can differ by ±1
Example: Core 2.1.0 works with Atoms 2.0.5 or 2.2.3

Cells (L2)¶

Version: Independent minor versions
Description: Células funcionales DSP
Compatibility: Must match Core MAJOR, MINOR can differ by ±2
Example: Core 2.1.0 works with Cells 2.3.0

Engines (L3)¶

Version: Independent major versions
Description: Engines completos
Compatibility: Can span multiple Core MAJOR versions
Example: Core 2.1.0 works with Engines 3.0.0

💻 Uso¶

CLI - Version Manager¶

# Ver versión actual
python version_manager.py current
# Output: Current version: 2.1.0-beta.3

# Bump version
python version_manager.py bump major   # 2.1.0 → 3.0.0
python version_manager.py bump minor   # 2.1.0 → 2.2.0
python version_manager.py bump patch   # 2.1.0 → 2.1.1

# Set lifecycle phase
python version_manager.py phase alpha --number 1
# Output: 2.1.0-alpha.1

python version_manager.py phase beta --number 3
# Output: 2.1.0-beta.3

python version_manager.py phase stable
# Output: 2.1.0

# Dry-run (preview sin escribir)
python version_manager.py bump major --dry-run

# Validar versión
python version_manager.py validate "2.1.0-rc.1"
# Output: ✅ Valid version format

# Info completa
python version_manager.py info

Programáticamente¶

from version_manager import VersionManager, VersionPart, LifecyclePhase

# Initialize manager
manager = VersionManager()

# Get current version
version = manager.get_current_version()
print(f"Current: {version}")  # 2.1.0-beta.3

# Bump version
new_version = manager.bump_version(VersionPart.MINOR)
print(f"New: {new_version}")  # 2.2.0

# Set lifecycle phase
version = manager.set_lifecycle_phase(LifecyclePhase.RC, number=1)
print(f"RC: {version}")  # 2.2.0-rc.1

# Validate
valid, message = manager.validate_version("3.0.0-alpha.1")
print(f"Valid: {valid}, Message: {message}")

# Check for breaking changes
commits = ["feat: new feature", "BREAKING CHANGE: API redesign"]
has_breaking = manager.check_breaking_changes(commits)
print(f"Has breaking changes: {has_breaking}")  # True

# Generate version info
info = manager.generate_version_info()
print(info)
# {
#   'version': '2.2.0-rc.1+20250315.a5f3b2c',
#   'version_short': '2.2.0',
#   'major': 2,
#   'minor': 2,
#   'patch': 0,
#   ...
# }

📁 Archivos¶

05_17_00_version_strategy/
├── version_strategy.yaml       # Configuración completa
├── lifecycle_phases.yaml       # Definición de fases
├── component_versions.yaml     # Versionado por componente
├── version_manager.py          # Herramienta principal
└── README.md                   # Este archivo

🔍 Detección de Breaking Changes¶

El sistema detecta automáticamente breaking changes de múltiples formas:

1. Análisis de Commits¶

# Commit con breaking change
git commit -m "feat!: redesign API

BREAKING CHANGE: ICellL2 interface modified
All cells must implement new process() signature"

2. API Diff Analysis¶

Compara interfaces públicas entre versiones para detectar: - Métodos removidos - Signatures modificadas - Parámetros cambiados - Return types diferentes

3. Preset Format Validation¶

Valida que formatos de presets sean compatible hacia atrás.

4. Binary Compatibility Check¶

Verifica ABI compatibility en librerías compiladas.

🎯 Deprecation Policy¶

Período de aviso: Mínimo 2 versiones MINOR

Proceso¶

Marcar como deprecated - Añadir @deprecated tag
Warning en código - Emitir deprecation warning
Documentar - Añadir a changelog
Migration path - Proveer guía de migración
Remover - En próxima versión MAJOR

Ejemplo¶

// Deprecated in 2.1.0
[[deprecated("Use processAudioStream() instead")]]
void oldProcessAudio(float* buffer, int size);

// Warning until 2.3.0
// Removed in 3.0.0

🚨 Hotfix Policy¶

Criterios para hotfix: - Critical security vulnerability - Data loss bug - Crash en operación común - Complete feature failure

Proceso: 1. Create hotfix branch from main 2. Implement minimal fix 3. Emergency review process 4. Bump PATCH version 5. Release immediately 6. Backport to active branches

Ejemplo:

main (2.1.3) → hotfix/security-patch → 2.1.4
↓ backport
develop (2.2.0-dev)
↓ backport
release/2.2-beta (2.2.0-beta.1)

📊 Métricas de Éxito¶

Métrica	Target	Medición
Version compliance	100%	Todas las versiones siguen SemVer
Breaking changes detected	100%	Automated detection
Lifecycle adherence	100%	Fases respetadas
User satisfaction	>4.5/5	Encuestas de usuarios

🔗 Integraciones¶

Upstream (depende de este)¶

05_17_01_branching_model - Branch naming usa versiones
05_17_02_commit_conventions - Commits determinan bumps
05_17_03_release_automation - Release basado en versiones

Tools¶

Git tags - Tagged con version numbers
CMakeLists.txt - Project VERSION variable
package.json - NPM version field
VERSION file - Plain text version

✅ Estado¶

Próximo: Implementar tests unitarios y validación

Última actualización: 2025-10-15 Versión: 1.0.0 Estado: ✅ Implementado y funcional