El Versionado Semántico, Semantic Versioning o SemVer 2.0.0, es una especificación para identificar la versión de librerías y componentes software que tienen una API pública; para facilitar la gestión de dependencias en proyectos de software.

Especificación detallada

El software que use Versionado Semántico debe declarar una API pública, precisa y completa en el mismo código o en documentación externa.

Utiliza el formato MAYOR.MENOR.PARCHE

Donde MAYOR, MENOR, y PARCHE son enteros no negativos. Cada valor se incrementará en 1 según corresponda.

Primeras versiones

  • Una versión liberada no podrá ser modificada. Cualquier modificación deberá liberarse como una nueva versión.
  • La versión cero (0.menor.parche) es para el desarrollo inicial. Cualquier cosa puede cambiar en cualquier momento y la API pública no es estable.
  • La versión uno (1.0.0) es para la primera API pública estable. La forma en que se incrementará la versión a partir de este momento dependerá de esta API pública y de cómo cambia.

Cómo incrementar la versión

Sólo se incrementará el valor PARCHE:

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

O sólo el valor MENOR (y el valor PARCHE se pondrá 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 funcionalidades, modificaciones o correcciones de forma considerable sin afectar a la API pública.
  • También puede incluir cambios de nivel PARCHE.

O sólo el valor MAYOR (y los valores PARCHE y MENOR se pondrán 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.

Versiones preliminares

Se identifican añadiendo 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 en su versión normal asociada.
  • Ejemplos: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Información de compilación (o desarrollo)

Puede incluirse añadiendo un signo más y una serie de 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-].
  • La información de compilación debe ignorarse al comparar versiones. Si dos versiones difieren sólo en la información de compilación entonces se considerarán la misma versión.
  • 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 entre sí deben separarse los valores MAYOR, MENOR, PARCHE y preliminar en ese orden (la información de compilación no se tiene en cuenta) y comparar cada uno de estos valores 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, la precedencia de dos versiones preliminares se determinará comparando cada identificador de izquierda a derecha hasta encontrar una diferencia: los identificadores con sólo dígitos se comparan numéricamente y los identificadores con letras o guiones se comparan según el orden ASCII. Los identificadores numéricos siempre tienen una prioridad menor que los identificadores no numéricos. Un grupo más grande de identificadores tiene una precedencia más alta que uno más pequeño, 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

  • Se acepta que la primera versión sea la 0.1.0, porque realmente no se empieza modificando o corrigiendo software, sino definiendo un conjunto inicial de funcionalidades, aunque no sean estables.
  • Si accidentalmente se libera como MENOR un cambio incompatible con la versión anterior, se recomienda resolver inmediatamente el problema y publicar una nueva versión MENOR que recupere la compatibilidad. Incluso en este caso es inaceptable modificar versiones ya liberadas.
  • 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.
  • El Versionado Semántico fue creado a finales de 2009 por Tom Preston-Werner (@mojombo), creador de Gravatar y co-fundador de GitHub.
0 comentarios

Dejar un comentario

¿Quieres unirte a la conversación?
Siéntete libre de contribuir!

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *