Semantic Versioning - Cheat Sheet

📋Reglas Básicas

Tipo	Cuándo incrementar	Ejemplo
MAJOR	Breaking changes (incompatible)	1.2.3 → 2.0.0
MINOR	Nueva funcionalidad (compatible)	1.2.3 → 1.3.0
PATCH	Bug fixes (compatible)	1.2.3 → 1.2.4

✅ Mejores Prácticas

Empezar con 1.0.0 para primera versión pública
Incrementar solo un número por release
Resetear números menores al incrementar mayor
Usar 0.x.x para desarrollo inicial
Documentar cambios en CHANGELOG.md

🧪Pre-releases

Alpha

v2.0.0-alpha.1
Desarrollo temprano, muchos bugs

Beta

v2.0.0-beta.1
Funcionalidad completa, testing

RC

v2.0.0-rc.1
Release candidate, casi listo

Stable

v2.0.0
Versión final estable

Orden de Precedencia:

                    1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
                

📊Ejemplos Prácticos

1.0.0

Primera versión pública

1.0.1

Bug fix

1.1.0

Nueva feature

2.0.0

Breaking change

2.1.0-alpha.1

Alpha de v2.1.0

2.1.0-beta.2

Segunda beta

🎯Tipos de Cambios

Tipo de Cambio	Versión	Descripción	Ejemplo
Breaking Change	MAJOR	Rompe compatibilidad	Cambiar API endpoint
Nueva Feature	MINOR	Agrega funcionalidad	Nuevo método público
Bug Fix	PATCH	Corrige comportamiento	Fix validación email
Performance	PATCH	Mejora rendimiento	Optimizar queries
Security Fix	PATCH	Parche de seguridad	Fix vulnerabilidad
Deprecation	MINOR	Marcar como obsoleto	Deprecar método old

🔢Versión 0.x.x

La versión 0.x.x es para desarrollo inicial. Todo puede cambiar en cualquier momento.

Versión 0.x.x	Versión 1.x.x+
0.1.0 → 0.2.0 (breaking)	1.0.0 → 2.0.0 (breaking)
0.1.0 → 0.1.1 (features/fixes)	1.0.0 → 1.1.0 (features)
API inestable	API estable y versionada
Para desarrollo	Para producción

⚠️ Importante: La versión 0.x.x NO garantiza compatibilidad hacia atrás.

⚡Commands Útiles

# NPM
npm version patch    # 1.0.0 → 1.0.1
npm version minor    # 1.0.0 → 1.1.0  
npm version major    # 1.0.0 → 2.0.0
npm version prerelease --preid=alpha # 1.0.0 → 1.0.1-alpha.0

# Git tags
git tag v1.0.0
git tag v1.1.0-beta.1
git push origin --tags

# Semantic Release
npx semantic-release --dry-run
npx semantic-release

# Manual bumping
npm version 1.2.3-alpha.1
npm version 2.0.0-rc.1

🚫Antipatrones

❌ No hagas esto

Versiones como v1.2.3.4 (cuatro números)
Fechas como versiones (v2024.01.15)
Saltar versiones (1.0.0 → 1.2.0 sin 1.1.0)
Cambiar versión sin cambios en código
Breaking changes en PATCH
Features nuevas en PATCH
Usar 'latest' como versión fija

✅ Hazlo bien

Sigue estrictamente MAJOR.MINOR.PATCH
Usa pre-releases para testing
Documenta todos los cambios
Automatiza el bumping de versiones
Mantén CHANGELOG actualizado
Usa conventional commits
Test antes de release

📦 Semantic Versioning