Conocimiento · TI · Datos · DX

Versionado semántico

Semantic Versioning

📂TI·Datos·DX⏱Lectura de 2 min📊Práctico🔗Relacionados 2

¿Qué es el versionado semántico?

Definición en una línea
Regla que asigna versiones de software como «mayor.menor.parche (ej.: 2.4.1)», para conocer la naturaleza del cambio solo con los números.
⚡ Resumen en 3 líneas
  • 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.

Capacitaciones en las que aparece este término · IA·DX
Cursos recomendados · Instructores recomendados · Mini cotización
🧮 Mini cotización · Criterio de honorarios
Aprox. KRW 1,200,000 (≈ US$900)Charla especial de 2 horas · hasta 20 personas · en coreano
Solicitar cotización formal con estas condiciones →
💡 Dicho de forma sencilla
Si en 2.4.1 cambia el primer número (mayor), es señal de «cambio grande, cuidado»: el riesgo de actualizar se conoce solo con el número.
Por qué es importante en la práctica
Permite juzgar si una actualización es segura solo con el número de versión, lo que hace predecible la gestión de dependencias complejas.
Origen y fuentes

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.

Fuente · Semantic Versioning (semver.org)
Entender con un caso

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
Términos relacionados
Capacitaciones relacionadas con este término
📚Crear sitios web prácticos con Claude CodeCapacitación corporativa de Nanum Consultoría · presencial / en líneaVer curso →
¿Necesita capacitación interna sobre este tema?
Reciba de inmediato un currículo y una cotización personalizados para su equipo.
Consultar sobre capacitación
Última modificación 2026-09-13 · Revisado por John Kim

Preguntas frecuentes

Se distinguen «ruptura de compatibilidad (mayor)», «nueva funcionalidad (menor)» y «corrección de errores (parche)» para dejar clara la naturaleza del cambio.
«Todavía no estable»: indica que la compatibilidad puede romperse con frecuencia.
Se distinguen «ruptura de compatibilidad (mayor)», «nueva funcionalidad (menor)» y «corrección de errores (parche)» para dejar clara la naturaleza del cambio.
«Todavía no estable»: indica que la compatibilidad puede romperse con frecuencia.