SemVer: por qué los números de versión tienen tres partes y cómo aplicarlo correctamente

Los números de versión que vemos en la mayoría de los paquetes, como 1.6.11, siguen la convención de Semantic Versioning (SemVer). Esta práctica asigna un significado concreto a cada uno de los tres componentes:

• MAJOR: se incrementa cuando se introduce un cambio que rompe la compatibilidad con versiones anteriores.
• MINOR: se incrementa al añadir funcionalidad de forma retrocompatible.
• PATCH: se incrementa al corregir errores sin afectar el comportamiento existente.

Con esa estructura, basta con observar el número para intuir el riesgo de una actualización: si solo cambia el PATCH, normalmente es seguro aplicar la versión de inmediato; si sube el MAJOR, conviene revisar detalladamente los cambios.

No basta con un número secuencial

Un esquema de versión simple, como v1, v2, v3, no comunica nada sobre la magnitud o el tipo de cambio. Cada actualización obligaría a leer las notas de la versión para saber si es segura. SemVer convierte el propio número en un canal de comunicación, permitiendo a operadores y desarrolladores decidir rápidamente si una actualización merece una revisión.

Comparaciones numéricas, no de cadena

Un error típico al comparar versiones es tratarlas como cadenas. En Python, la comparación de strings evalúa carácter a carácter, de modo que "1.10.0" > "1.9.0" resulta falso porque el carácter "1" de la segunda posición se compara con "9". La solución es convertir cada segmento a entero y comparar tuplas:

remote = tuple(int(x) for x in remote_version.split('.'))
current = tuple(int(x) for x in current_version.split('.'))
return remote > current

Esta lógica garantiza que (1, 10, 0) > (1, 9, 0) sea verdadero, alineando la ordenación con la intención semántica.

Mantener la versión en un solo lugar

En proyectos reales, la cadena de versión suele estar duplicada en varios archivos: código fuente, configuraciones de instaladores, metadatos de distribución y enlaces de descarga. La desincronización es fácil y puede generar instaladores con versiones obsoletas. La solución mostrada en el artículo consiste en un script que actualiza simultáneamente todos los archivos y ofrece un modo --check que verifica la consistencia antes de iniciar la compilación. Si alguna referencia diverge, el proceso se detiene, obligando a corregir la discrepancia.

En resumen, SemVer no es solo una convención de nombres; es una herramienta de diseño que facilita la gestión de cambios, la automatización de despliegues y la confianza en las actualizaciones.

Aunque el artículo no menciona una herramienta oficial, la práctica de centralizar la versión en un único archivo y validar su propagación con scripts es aplicable a cualquier stack, desde proyectos Python hasta paquetes npm o imágenes Docker.