¿Qué es el versionado semántico?

El versionado semántico, también conocido como SemVer, es un conjunto de reglas y requisitos que establecen cómo asignar y aumentar los números de versión en el software. Este sistema fue creado por Tom Preston-Werner, cofundador de GitHub, para resolver el problema conocido como "el infierno de las dependencias" (dependency hell).

El problema que resuelve el versionado semántico

Cuando desarrollamos software que depende de paquetes o bibliotecas externas, nos enfrentamos a varios desafíos:

1. Compatibilidad: ¿Cómo saber si una nueva versión de una dependencia romperá nuestro código?
2. Actualización: ¿Cuándo es seguro actualizar a una nueva versión?
3. Comunicación: ¿Cómo comunicar a los usuarios la magnitud de los cambios en una nueva versión?

El versionado semántico proporciona una solución a estos problemas mediante un sistema claro y estructurado para numerar las versiones de software.

La estructura del versionado semántico

El formato básico del versionado semántico es:

MAYOR.MENOR.PARCHE

Por ejemplo: 2.4.1

Donde:

• MAYOR (X): Se incrementa cuando se realizan cambios incompatibles con versiones anteriores (breaking changes).
• MENOR (Y): Se incrementa cuando se añade funcionalidad compatible con versiones anteriores.
• PARCHE (Z): Se incrementa cuando se realizan correcciones de errores compatibles con versiones anteriores.

Etiquetas adicionales

El versionado semántico también permite etiquetas adicionales para versiones preliminares y metadatos:

• Pre-lanzamiento: 1.0.0-alpha, 1.0.0-beta.1, 1.0.0-rc.1
• Metadatos de compilación: 1.0.0+20130313144700, 1.0.0-beta.1+exp.sha.5114f85

Reglas del versionado semántico

1. Versión inicial

El desarrollo inicial comienza con la versión 0.1.0 o 0.y.z. La versión 1.0.0 define la API pública inicial.

2. Incremento de versión MAYOR (X)

Se incrementa cuando se realizan cambios incompatibles en la API pública:

• Eliminación de funcionalidades
• Cambios en parámetros o tipos de retorno
• Renombrado de funciones o clases públicas

Ejemplos:

• 1.0.0 → 2.0.0
• 2.4.1 → 3.0.0

3. Incremento de versión MENOR (Y)

Se incrementa cuando se añade funcionalidad compatible con versiones anteriores:

• Nuevos métodos o clases
• Nuevas opciones en funciones existentes
• Deprecación de funcionalidades (marcándolas como obsoletas pero manteniéndolas)

Ejemplos:

• 1.0.0 → 1.1.0
• 2.4.1 → 2.5.0

4. Incremento de versión PARCHE (Z)

Se incrementa cuando se realizan correcciones de errores compatibles con versiones anteriores:

• Corrección de bugs
• Mejoras de rendimiento
• Cambios internos que no afectan la API pública

Ejemplos:

• 1.0.0 → 1.0.1
• 2.4.1 → 2.4.2

5. Versiones preliminares

Las versiones preliminares (pre-release) indican que la versión no es estable:

• 1.0.0-alpha: Primera versión alfa
• 1.0.0-alpha.1: Actualización de la versión alfa
• 1.0.0-beta: Versión beta
• 1.0.0-rc.1: Release candidate 1

6. Precedencia de versiones

La precedencia se calcula separando la versión en MAYOR, MENOR, PARCHE e identificadores de pre-lanzamiento:

1. MAYOR tiene precedencia sobre MENOR y PARCHE
2. MENOR tiene precedencia sobre PARCHE
3. Una versión con pre-lanzamiento tiene menor precedencia que su versión normal
   • Ejemplo: 1.0.0-alpha < 1.0.0

Beneficios del versionado semántico

1. Claridad en la comunicación

Los desarrolladores y usuarios pueden entender inmediatamente el impacto de una actualización:

• Versión MAYOR: "Prepárate para cambios importantes"
• Versión MENOR: "Hay nuevas funcionalidades, pero tu código existente seguirá funcionando"
• Versión PARCHE: "Puedes actualizar con confianza, solo son correcciones"

2. Gestión de dependencias más eficiente

Los gestores de paquetes pueden trabajar de manera más inteligente:

• ^1.2.3: Compatible con versiones >= 1.2.3 y < 2.0.0
• ~1.2.3: Compatible con versiones >= 1.2.3 y < 1.3.0

3. Adopción más rápida

Los usuarios pueden adoptar nuevas versiones con mayor confianza, sabiendo que las actualizaciones de versiones MENOR y PARCHE no romperán su código existente.

4. Mejor planificación de desarrollo

Los equipos pueden planificar mejor sus ciclos de desarrollo:

• Cambios incompatibles se agrupan en versiones MAYORES
• Nuevas funcionalidades se lanzan en versiones MENORES
• Correcciones urgentes se pueden lanzar rápidamente como versiones PARCHE

Implementación del versionado semántico en proyectos Git

1. Definir la API pública

Antes de comenzar con el versionado semántico, define claramente qué constituye tu API pública:

• Funciones y clases exportadas
• Formatos de datos
• Protocolos de comunicación
• Comportamientos documentados

2. Documentar los cambios

Mantén un archivo CHANGELOG.md que registre todos los cambios significativos:

# Changelog

## [2.0.0] - 2023-04-15
### Cambios incompatibles
- Eliminada la función `oldFunction()`
- Cambiado el parámetro `options` de `someFunction()` para usar un objeto en lugar de argumentos separados

### Añadido
- Nueva clase `NewFeature` para manejar X

### Corregido
- Solucionado problema de rendimiento en Y

## [1.1.0] - 2023-03-10
### Añadido
- Nueva función `newFunction()`

### Corregido
- Solucionado error #123

3. Usar etiquetas Git para marcar versiones

Usa etiquetas Git para marcar cada versión en tu repositorio:

# Crear una etiqueta anotada
git tag -a v1.0.0 -m "Versión 1.0.0"

# Enviar la etiqueta al repositorio remoto
git push origin v1.0.0

4. Automatizar el proceso

Considera usar herramientas para automatizar la gestión de versiones:

• semantic-release: Determina automáticamente la próxima versión basándose en los mensajes de commit
• standard-version: Genera automáticamente el CHANGELOG y crea la etiqueta Git
• commitizen: Ayuda a escribir mensajes de commit estandarizados que facilitan el versionado automático

Casos de estudio

Node.js

Node.js sigue estrictamente el versionado semántico:

• Node.js 12 a Node.js 14: Cambio MAYOR
• Node.js 14.15.0 a Node.js 14.16.0: Cambio MENOR
• Node.js 14.16.0 a Node.js 14.16.1: Cambio PARCHE

npm

npm utiliza el versionado semántico para todas sus dependencias, con un sistema de especificación de rangos:

• package@1.0.0: Exactamente la versión 1.0.0
• package@^1.0.0: Compatible con 1.0.0 (>= 1.0.0 < 2.0.0)
• package@~1.0.0: Aproximadamente equivalente a 1.0.0 (>= 1.0.0 < 1.1.0)

Errores comunes en el versionado semántico

1. Incrementar la versión MAYOR por cambios menores

No incrementes la versión MAYOR solo porque lanzaste nuevas funcionalidades importantes. La versión MAYOR es específicamente para cambios incompatibles.

2. No incrementar la versión MAYOR cuando se rompe la compatibilidad

Este es un error grave que puede causar problemas a tus usuarios. Cualquier cambio incompatible debe incrementar la versión MAYOR.

3. Usar 0.y.z como versión estable

Las versiones 0.y.z están destinadas al desarrollo inicial. No deberían usarse para software en producción que requiere estabilidad.

4. Modificar una versión ya publicada

Una vez que una versión específica ha sido publicada, su contenido no debe modificarse. Cualquier cambio debe publicarse como una nueva versión.

Versionado semántico y ciclo de vida del software

El versionado semántico se alinea naturalmente con diferentes fases del ciclo de vida del software:

Desarrollo inicial (0.y.z)

• Fase exploratoria
• API inestable
• Cambios frecuentes y potencialmente incompatibles

Lanzamiento inicial (1.0.0)

• Definición de la API pública estable
• Compromiso con la compatibilidad hacia adelante
• Base para la comunidad de usuarios

Mantenimiento (x.y.z)

• Adición de nuevas funcionalidades (x.y+1.z)
• Corrección de errores (x.y.z+1)
• Ocasionalmente, cambios incompatibles planificados (x+1.0.0)

Fin de vida (EOL)

• Última versión MENOR con correcciones de seguridad
• Comunicación clara sobre la migración a nuevas versiones MAYORES
• Periodo de soporte extendido para versiones empresariales

Conclusión

El versionado semántico es mucho más que un sistema para numerar versiones; es una herramienta de comunicación que ayuda a gestionar las expectativas y reduce la fricción entre desarrolladores y usuarios. Al seguir estas reglas, puedes comunicar claramente el impacto de los cambios en tu software y ayudar a otros desarrolladores a entender cómo interactuar con tus proyectos de manera segura.

En la próxima lección, profundizaremos en la convención SemVer y aprenderemos cómo implementarla de manera efectiva en proyectos Git, incluyendo la integración con flujos de trabajo de integración continua y entrega continua (CI/CD).