Versionado Semántico

El Versionado Semántico, Semantic Versioning o SemVer 2.0.0, facilita la gestión de dependencias software.

Es una especificación para identificar la versión de las librerías y componentes software que declaran una API pública precisa y completa en el mismo código o en documentación externa.

Tabla de contenidos

Usa el formato MAYOR.MENOR.PARCHE

Cómo incrementar la versión

Primeras versiones

Información opcional

Para versiones preliminares

Para versiones de compilación (o desarrollo)

Orden de precedencia de las versiones

Notas relevantes

Referencias

Usa el formato MAYOR.MENOR.PARCHE

En el original MAJOR.MINOR.PATCH. Cada valor es un número natural que se incrementa en 1 según los siguientes criterios:

Cómo incrementar la versión

Incrementar PARCHE:

Si se han incluido modificaciones o correcciones que dejan la API compatible con la versión anterior.

Incrementar MENOR (poniendo PARCHE a 0):

Si se introduce una nueva funcionalidad que mantiene la API compatible con la versión anterior.
Si alguna funcionalidad de la API se marca como obsoleta («deprecated») para ser eliminada en una versión MAYOR posterior.
Si se añaden suficientes funcionalidades, modificaciones o correcciones sin afectar a la API pública.
También puede incluir cambios de nivel PARCHE.

Incrementar MAYOR (poniendo PARCHE y MENOR a 0):

Si se introducen en la API pública cambios que no sean compatibles con la versión anterior.
También puede incluir cambios de nivel PARCHE y MENOR.

Primeras versiones

La versión cero 0.menor.parche es para el desarrollo inicial. Cambios constantes en una API pública no es estable.

La versión uno 1.0.0 es para la primera API pública estable. Y se irá incrementando según cambie esta API pública.

Información opcional

Para versiones preliminares

Añadir un guión y una serie de identificadores separados por puntos después del valor PARCHE.

Los identificadores deben incluir sólo caracteres alfanuméricos ASCII y guión [0-9A-Za-z-].
Los identificadores numéricos no deben contener ceros iniciales.
Una versión preliminar puede ser inestable y no cumplir con los requisitos de compatibilidad previstos.
Ejemplos: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Para versiones de compilación (o desarrollo)

Añadir un signo más y los identificadores separados por puntos después del valor PARCHE o preliminar.

Los identificadores deben incluir sólo caracteres alfanuméricos ASCII y guión [0-9A-Za-z-].
Si dos versiones difieren sólo en la información de compilación entonces se considerarán la misma.
Ejemplos: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

Orden de precedencia de las versiones

Para comparar versiones separar los valores MAYOR, MENOR, PARCHE y preliminar en ese orden (la información de compilación no se considera) y comparar cada valor de izquierda a derecha:

Los valores MAYOR, MENOR y PARCHE siempre se comparan numéricamente.
Ejemplo: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.
Para versiones iguales, una versión preliminar tiene una precedencia menor que la normal.
Ejemplo: 1.0.0-alfa < 1.0.0.
Para versiones iguales comparar cada identificador de izquierda a derecha hasta encontrar una diferencia. Con sólo dígitos se comparan numéricamente, y con letras o guiones según el orden ASCII. Los numéricos tienen una prioridad menor que los no numéricos. Mayor número de identificadores implica una precedencia más alta si todos los anteriores son iguales.
Ejemplo: 1.0.0-alfa < 1.0.0-alfa.1 < 1.0.0-alfa.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Notas relevantes

Una versión liberada no podrá ser modificada. Cualquier cambio debe liberarse como nueva versión.
Usa 0.1.0 para la primera versión, porque realmente no se empieza modificando o corrigiendo software, sino definiendo funcionalidades, aunque no sean estables.
Si se libera un cambio MENOR incompatible con la versión anterior, resolver inmediatamente el problema publicando una nueva versión MENOR que recupere la compatibilidad.
Si se actualizan las propias dependencias del software sin cambiar la API pública, seguirá siendo compatible con la versión anterior. Se considerará de nivel PARCHE o MENOR si el cambio se hizo para corregir un fallo del software o para añadir una funcionalidad nueva. Los proyectos que explícitamente utilicen las mismas dependencias deberán resolver los conflictos que pudieran derivarse del cambio.