Calculadora SemVer — Herramienta Online Gratuita

¿Qué es el Versionado Semántico?

El Versionado Semántico (SemVer) es una especificación de versionado que utiliza un formato de tres números: MAJOR.MINOR.PATCH (por ejemplo, 2.4.1). Proporciona una forma estándar de comunicar la naturaleza de los cambios en cada versión, ayudando a los desarrolladores a entender qué esperar cuando actualizan una dependencia.

La especificación SemVer (semver.org) define reglas claras: incremente MAJOR para cambios incompatibles, MINOR para nuevas funcionalidades retrocompatibles y PATCH para correcciones de errores retrocompatibles.

Cuándo Incrementar Cada Parte de la Versión

• MAJOR (cambio incompatible): Se eliminó un método de API pública, se cambiaron firmas de funciones, se eliminó comportamiento obsoleto, se cambió el flujo de autenticación.
• MINOR (nueva funcionalidad): Se agregó un nuevo endpoint, se agregaron parámetros opcionales a funciones existentes, se agregaron nuevas opciones de configuración.
• PATCH (corrección de error): Se corrigió un fallo, se corrigió un comportamiento incorrecto, mejora de rendimiento sin cambio de API, corrección de documentación.

Sintaxis de Rangos de Versión en npm

• ^1.2.3 — Compatible con 1.2.3. Permite actualizaciones MINOR y PATCH (>=1.2.3 <2.0.0)
• ~1.2.3 — Aproximadamente equivalente. Permite solo actualizaciones PATCH (>=1.2.3 <1.3.0)
• >=1.2.3 <2.0.0 — Rango explícito, intención muy clara
• 1.x — Cualquier versión con versión major 1
• * — Cualquier versión (peligroso para producción)
• 1.2.3 — Solo versión exacta (sin actualizaciones)

Versionado Semántico en la Práctica: Más Allá de la Teoría

El Versionado Semántico (SemVer) proporciona un contrato claro entre autores de bibliotecas y consumidores sobre qué cambios esperar en cada release. Sin embargo, las decisiones de versionado en el mundo real son más matizadas que la simple fórmula MAJOR.MINOR.PATCH.

Cuándo Incrementar Cada Número de Versión

• MAJOR (cambios incompatibles): Eliminar una API pública, cambiar una firma de función, renombrar módulos exportados, dejar de soportar una versión de runtime, o cambiar el comportamiento predeterminado del que dependen usuarios existentes.
• MINOR (nuevas características, compatible): Agregar nuevas funciones, endpoints u opciones. Agregar parámetros opcionales a funciones existentes. Deprecar (pero no eliminar) APIs existentes.
• PATCH (solo correcciones): Corregir comportamiento incorrecto, parches de seguridad, mejoras de rendimiento que no cambian la API, correcciones de documentación.

Estrategias de Rango de Versión para package.json

• ^1.2.3 (caret — predeterminado de npm): Permite actualizaciones MINOR y PATCH: ≥1.2.3 <2.0.0. Mejor para la mayoría de dependencias.
• ~1.2.3 (tilde): Permite solo actualizaciones PATCH: ≥1.2.3 <1.3.0. Más conservador.
• 1.2.3 (exacto): Bloquea exactamente esta versión. Más conservador — usa para dependencias críticas donde cualquier cambio es riesgoso.

Versiones Pre-release y Metadatos de Build

SemVer soporta identificadores pre-release (1.0.0-alpha.1, 2.0.0-beta.3, 1.0.0-rc.1). Las versiones pre-release tienen menor precedencia que la versión release: 1.0.0-alpha < 1.0.0. Los metadatos de build (1.0.0+20260314) se ignoran en comparaciones de precedencia pero son útiles para rastrear información de build.

Preguntas Frecuentes sobre Versionado Semántico

¿Cuál es la diferencia entre ^1.0.0 y ~1.0.0 en npm?

El acento circunflejo (^) permite actualizaciones compatibles dentro de la misma versión major: ^1.0.0 permite cualquier versión >=1.0.0 y <2.0.0, permitiendo tanto actualizaciones minor como patch. La virgulilla (~) es más restrictiva: ~1.0.0 permite solo actualizaciones patch, coincidiendo con >=1.0.0 y <1.1.0. npm usa el acento circunflejo (^) como valor predeterminado. Use virgulilla cuando necesite un control más estricto sobre las versiones instaladas.

¿Cuándo debo incrementar el número de versión major?

Incremente major (por ejemplo, de 1.x.x a 2.0.0) solo para cambios incompatibles que no son retrocompatibles con la versión anterior. Esto incluye: eliminar o renombrar un método de API pública, cambiar la firma de parámetros de una función, dejar de soportar un runtime o entorno previamente soportado, o cambiar el comportamiento predeterminado de forma que rompa integraciones existentes. Las adiciones no incompatibles siempre van a minor, y las correcciones de errores siempre van a patch.

¿Qué significa un número de versión que comienza con 0?

Las versiones que comienzan con 0 (por ejemplo, 0.x.x) indican que el software está en desarrollo inicial y la API pública aún no es estable. Bajo SemVer, cualquier cosa puede cambiar en cualquier momento durante el desarrollo 0.x — incluyendo cambios incompatibles con incrementos de versión minor (de 0.1.0 a 0.2.0). Solo incremente a 1.0.0 cuando esté listo para comprometerse con una API pública estable y documentada para la cual mantendrá retrocompatibilidad.

¿Cómo publico una versión prerelease usando SemVer?

Agregue un identificador de prerelease después de un guión: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. Las versiones prerelease tienen menor precedencia que la versión final: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. En npm, publique prereleases con npm publish --tag next para que no se instalen por defecto. Los selectores de rango con acento circunflejo y virgulilla no coinciden automáticamente con versiones prerelease.

Herramientas Relacionadas para Desarrolladores

• Buscador de Comandos Git — encuentre el comando Git exacto para etiquetar, crear ramas y publicar versiones
• Generador de Docker Compose — genere configuraciones docker-compose.yml listas para producción
• Inspector de Archivos .ENV — valide archivos de entorno y detecte secretos expuestos
• Decodificador e Inspector JWT — decodifique tokens JWT e inspeccione claims de forma segura en el navegador
• Ver todas las herramientas gratuitas para desarrolladores