Versionado semántico
Semantic Versioning
¿Qué es el versionado semántico?
- Versionado en mayor.menor.parche
- Identificar la naturaleza del cambio por los números
- Gestión de compatibilidad
Lo que realmente cambia con el versionado semántico es quién decide cuándo actualizar. Sin una regla, hay que leer todas las notas de versión y decidir una por una; con la regla, el gestor de paquetes ejecuta mecánicamente la instrucción «sube hasta la versión menor y no toques la mayor». Notaciones como ^1.4.0 en package.json o ~=1.4 en Python son esa instrucción. El trabajo de verificación humana pasa a ser un valor de configuración de la herramienta, y por eso un proyecto con 200 a 300 dependencias funciona revisando a mano solo las actualizaciones de versión mayor.
Entre los detalles hay excepciones que los profesionales suelen pasar por alto. El rango 0.y.z no está protegido por las reglas: la especificación oficial aclara que «en la versión 0.x la compatibilidad puede romperse en cualquier momento». Desde que se publica 1.0.0, la API pública queda fija. Una prerelease como 1.0.0-beta.2, con su guion, se considera una versión inferior a la 1.0.0 final, y los metadatos de compilación que van después del signo más se ignoran por completo en las comparaciones. Su propósito es distinto del de CalVer, que usa la fecha como versión, como en Ubuntu 24.04; mezclarlos dentro de una misma organización solo genera confusión.
En la práctica, el malentendido más común es creer que el número de versión es una garantía. El número es una declaración que pone quien hace el despliegue, no un hecho verificado. De hecho, no son pocas las bibliotecas que cambian valores predeterminados de configuración en una versión de parche, y los equipos internos suelen ocultar cambios incompatibles en versiones menores porque «si subimos la versión mayor, a otros equipos no les gusta». Además, si no se sube el archivo lock al repositorio, el mismo comando de instalación produce resultados distintos en la PC del desarrollador y en el servidor de producción, y encontrar la causa de una falla puede tomar días.
Seungtae ParkInstructor práctico de AX que enseña creando por sí mismo proyectos de automatización del marketing y de desarrollo de negocio con IA
John KimCEO de Nanum Consultoría y autor de «Diseño del marketing B2B»Norma definida por Tom Preston-Werner (cofundador de GitHub) en semver.org, que se convirtió en el estándar de facto del ecosistema de código abierto.
Veamos un caso hipotético. A, una empresa que opera un SaaS de logística con 140 colaboradores, sufrió tres fallas justo después de desplegar en el cuarto trimestre del año pasado. Al rastrear la causa, las tres se originaron en actualizaciones automáticas de bibliotecas externas, y dos de ellas eran «correcciones de errores» que solo cambiaban el último dígito de la versión.
- El responsable de backend, Kim, revisó el registro de despliegues de un mes y encontró 47 paquetes que se habían actualizado automáticamente; además, el archivo lock ni siquiera estaba en el repositorio.
- Cuando el CTO preguntó «si solo cambió el último número, ¿por qué se cayó el servicio?», el responsable Kim mostró en pantalla el commit en el que la biblioteca de autenticación pasó de 0.9.3 a 0.9.4 y el valor predeterminado de vencimiento del token cambió de 24 horas a 1 hora.
- El equipo fijó por completo la versión de los paquetes 0.x, usó rangos caret solo para versiones 1.0.0 o superiores y, sin excepción, versionó el archivo lock. Escribió estas tres reglas en lo alto del README del repositorio.
- Aplicamos el mismo criterio a los 12 módulos comunes internos e incluimos en la lista de revisión de código el punto «si se elimina aunque sea un solo campo de la respuesta de la API, se sube la versión mayor». En el primer mes, el módulo de liquidaciones pasó de 2.7.0 a 3.0.0.
- Seis meses después, las fallas justo después de un despliegue bajaron de 3 por trimestre a 0, y el tiempo promedio para revisar un PR de actualización pasó de 40 a 10 minutos.