guides

El versionado semántico, casi siempre abreviado como SemVer, es un conjunto simple de reglas para numerar las versiones de software de forma que el propio número de versión te diga qué cambió. En lugar de un contador sin sentido, una versión SemVer son tres números, MAJOR.MINOR.PATCH, como 2.4.1, y cada posición tiene un significado definido. Una vez que conoces las reglas, puedes mirar un incremento de versión y entender de inmediato si una actualización es segura, añade funcionalidades o podría romper tu código.

Cada una de las tres partes responde a una pregunta distinta. MAJOR (el primer número) aumenta cuando haces cambios incompatibles y rompedores en la API pública, actualizar podría obligarte a modificar tu propio código. MINOR (el segundo) aumenta cuando añades nueva funcionalidad de forma retrocompatible, nuevas características que puedes adoptar o ignorar. PATCH (el tercero) aumenta para correcciones de errores retrocompatibles, arreglos seguros que no cambian la forma en que se usa el software.

Hay dos reglas mecánicas que confunden a la gente. Cuando aumentas MAJOR, reinicias MINOR y PATCH a cero: tras 1.4.2, un cambio rompedor pasa a ser 2.0.0, no 2.4.2. Cuando aumentas MINOR, reinicias PATCH a cero: tras 1.4.2, una nueva característica pasa a ser 1.5.0. Así que los números a la derecha siempre se reinician cuando un número a su izquierda sube.

SemVer también tiene una regla especial para el desarrollo temprano. Cualquier versión que empiece por 0, como 0.3.1, se considera inestable, y las garantías normales no se aplican del todo. Durante la fase 0.x, la API puede cambiar en cualquier momento, así que trata esas versiones con cautela. El salto a 1.0.0 es una señal deliberada: significa que el autor se compromete con una API pública estable y con seguir las reglas de SemVer a partir de ese momento.

Más allá de los tres números principales, SemVer admite etiquetas de pre-lanzamiento y de compilación. Una versión de pre-lanzamiento añade un guion y un identificador, como 1.0.0-alpha, 1.0.0-beta.2 o 1.0.0-rc.1, y tiene una precedencia menor que la versión final, de modo que 1.0.0-rc.1 va antes que 1.0.0. Los metadatos de compilación pueden añadirse tras un signo más, como 1.0.0+20260715, pero se ignoran al comparar versiones. Esto permite a los equipos publicar compilaciones de prueba sin fingir que son lanzamientos terminados.

La razón por la que todo esto importa es la gestión de dependencias. Cuando tu proyecto depende de una biblioteca, rara vez fijas una versión exacta para siempre; permites un rango. Los gestores de paquetes usan SemVer para hacer que esos rangos sean seguros. En npm, por ejemplo, un rango con acento circunflejo como ^1.2.3 significa cualquier versión desde 1.2.3 hasta 2.0.0 sin incluirla, todas las actualizaciones retrocompatibles, ninguna de las rompedoras. Un rango con tilde como ~1.2.3 es más estricto, permitiendo actualizaciones de parche hasta 1.3.0 sin incluirla.

Esos rangos solo funcionan porque todo el mundo está de acuerdo en qué significa un incremento de versión. Si una biblioteca publica un cambio rompedor pero solo incrementa PATCH, puede romper de forma silenciosa cada proyecto que confió en el rango. Ese es el contrato social en el corazón de SemVer: el número es una promesa sobre la compatibilidad, y honrarla es lo que evita que todo el ecosistema de actualizaciones automáticas se desmorone.

SemVer está definido por una especificación corta y legible en semver.org, y es el esquema usado por npm, Cargo y un sinfín de otros registros y herramientas de paquetes. No es la única forma de versionar software, algunos proyectos usan versionado por calendario (como 2026.07) o su propio esquema, pero SemVer es el más ampliamente entendido, y conocerlo hace que leer registros de cambios y rangos de dependencias sea mucho más fácil.

La conclusión práctica: lee una versión como si fuera una frase. Un salto en el primer número dice detente y comprueba si hay cambios rompedores antes de actualizar. Un salto en el segundo dice que hay nuevas características pero tu código existente está a salvo. Un salto en el tercero dice que es una corrección de errores segura. Ese único hábito, leer la posición que cambió, convierte un número opaco en un mensaje claro sobre el riesgo.