Versificación semántica

Versificación semántica

1) Qué es SemVer y por qué lo necesita

• MAJOR - Cambios incompatibles (breaking changes).
• MINOR es una nueva funcionalidad compatible con la API.
• PARCH: correcciones de defectos reversibles y compatibles.

Objetivo: negociar la estabilidad de los contratos y reducir el coste de las actualizaciones.

2) Formato de versión

• `MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD]`

`1. 4. 7 '- lanzamiento estable.
`1. 5. 0-rc. 2 '- pre-lanzamiento (release candidate # 2).
`2. 0. 0+linux. arm64 '- metadatos build (no afectan a la comparación de versiones).

1. Primero se comparan 'MAJOR', luego 'MINOR' y luego 'PATCH'.

2. Las versiones anteriores son más pequeñas que la versión estable correspondiente: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Los metadatos de construcción ('+...') no afectan al orden: '1. 2. 0+001 == 1. 2. 0`.

3) Lo que se considera un cambio de breaking

• Eliminación/cambio de nombre/cambio de firma de métodos públicos/endpoints.
• Cambiar el formato de entrada/salida (diagrama JSON, tipos).
• Modificación de contratos de errores (códigos/estructuras).
• Cambiar side-effects/SLAs (por ejemplo, límites estrictos o nuevos campos obligatorios).

No breaking (con implementación correcta): agregar campos opcionales, extender enum con nuevos valores (si el cliente los ignora), nuevos endpoints, nuevas banderas con impagos que no afectan a las llamadas actuales.

4) Pre-lanzamientos y estrategias de canal

• Etiquetas: 'alpha', 'beta', 'rc'. Ejemplo: '2. 3. 0-beta. 3`.
• Canales: nightly → alpha → beta → rc → stable.
• Política: las preemergencias no deben caer como dependencias transitivas para los ensambles prod predeterminados.

5) Rangos de versión y precisión de las dependencias

5. 1 Node/npm (SemVer predeterminado)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(permite MINOR/PATCH, fija MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(permite PATCH dentro de MINOR).
`1. 4. x '- cualquier parche en 1. 4.
Pin exacto: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- límites claros.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- inclusive/exclusivo.
Se recomienda una patada estricta para artefactos prod-críticos.

5. 4 Go modules

Siempre etiquetas completas 'vMAJOR. MINOR. PATCH ';' v2 + 'requiere el sufijo del módulo '/v2'.

Recomendación: para aplicaciones, pines de precisión (builds reproducibles). Para las bibliotecas - caret-ranks (facilitar actualizaciones sin roturas).

6) CHANGELOG и Conventional Commits

El registro de cambios estructurado aumenta la transparencia.

feat(payments): add PIX refund endpoint fix(api): correct 400 → 422 on invalid payload perf(cache): reduce p99 by 20%
refactor(core): extract rule engine docs: update API usage examples chore(deps): bump lodash to 4. 17. 21 feat!: remove legacy webhook v1 (BREAKING CHANGE:...)

Типы: `feat`, `fix`, `perf`, `docs`, `refactor`, `chore` и т. д.
El signo de exclamación o bloque 'BREAKING CHANGE' anuncia la subida MAYOR.
El CHANGELOG se genera a partir del historial de commits (release-notes por bots).

7) Política de versionamiento para API

API públicas: SemVer estricto; breaking → MAJOR.
HTTP/NAT: versionar por URL/encabezado: '/v1/... ', '/v2/...' o'Accept: application/vnd. org. service. v2+json`.
Esquemas JSON: extensiones menores: nuevos campos opcionales; mayor - Eliminar/modificar las obligatorias.
gRPC/Protobuf: añadir nuevos campos con nuevos números; No vuelva a utilizar los números de campo; eliminar → deprecate en lugar de «romper» los existentes.

8) Esquemas de datos y migración

Las migraciones de DB se sincronizan con las versiones de la aplicación: 'app @ 1. 8. 0 'requiere' schema @ 1. 8. x`.
Para los cambios de esquema breaking - fases: expand (añadir), migrate, contract (eliminar). Eleve la versión a MAJOR sólo cuando elimine el contrato anterior.
Admita doble escritura/lectura durante la migración.

9) Monorepos y microservicios

Multi-package: cada paquete es su 'MAJOR. MINOR. PATCH`; ciclo raíz común de lanzamientos sólo para meta artefactos.

• Versiones independientes (Lerna/Changesets) - refuerza el aislamiento.
• Lock-step es más fácil de comunicar, pero más falsos MAJOR-s.
• Para microservicios, confirme los contratos (OpenAPI/Protobuf) con una versión separada: 'aprox @ 2. 1. 0 ', el servicio le sigue.

10) Automatización de lanzamientos en CI/CD

• `fix` → `PATCH`, `feat` → `MINOR`, `!`/`BREAKING` → `MAJOR`.

yaml
Pseudo-workflow steps:
- run: npx semantic-release
- run: git tag v$NEW_VERSION && git push --tags
- run: cosign sign ghcr. io/org/app:v$NEW_VERSION

Generación de CHANGELOG, publicación de libretas, actualización de dependencias en GitOps-repo, comprobación de que 'main' siempre apunta a la última etiqueta estable.

11) Política de privación (política de depreción)

Anuncio: marque la funcionalidad como deprecated en la versión MINOR, vamos EOL plazo (por ejemplo, 90 días).
Observabilidad: lógica el uso de endpoints obsoletos con contexto usuario/tenant.
Eliminación: en el siguiente MAJOR. Documente la ruta de migración.

12) Ejemplos y plantillas

12. 1 Expresión regular de validación SemVer

regex
^(0    [1-9]\d)\.(0    [1-9]\d)\.(0    [1-9]\d)(?--([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))? (?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)))?$

12. 2 Ejemplos de comparación

`1. 2. 3` < `1. 10. 0 '(comparación por MINOR).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Política de dependencia (ejemplo YAML)

yaml policy:
libraries:
default_range: "^MAJOR. MINOR. PATCH"
pin_security_critical: true services:
pin_exact: true allow_prerelease_in_nonprod: true api_contract:
require_same_minor: true forbid_major_mismatch: true

13) Anti-patrones

Uso de 'latest '/etiquetas flotantes en la venta.
Mejora de MAJOR sin roturas reales («versiones de marketing»).
Cambios ocultos de breaking bajo la apariencia de 'PATCH'.
Pre-lanzamientos en dependencias transitivas de aplicaciones prod.
Cambiar artefacto sin una nueva etiqueta (versiones mutables).
Versiones inconsistentes del código y del diagrama DB.

14) Lista de verificación de implementación (0-45 días)

0-10 días

Acepte SemVer como estándar obligatorio, apruebe los criterios de rotura.
Habilita Conventional Commits y la plantilla PR con el campo 'BREAKING CHANGE'.

11-25 días

Conecte semantic-release/changesets, autogeneración CHANGELOG.
Configure la firma y publicación de artefactos con la etiqueta 'vX. Y.Z`.

26-45 días

Introduzca la política de depreción y la telemetría del uso de APIs obsoletas.
Sincronice las versiones de los contratos (OpenAPI/Proto) y los servicios.
Prohíba las etiquetas 'latest' y mutables a nivel de política (ORA/CI Regulations).

15) Métricas de madurez

% de los artefactos publicados únicamente con la etiqueta SemVer.
Tiempo medio de migración entre versiones MINOR.
Número de incidentes debido a cambios de breaking ocultos.
Cobertura de Comités Conventuales en repositorios (> 95%).
Proporción de dependencias sin rangos flotantes en la venta (> 90%).

16) Cuando SemVer no es necesario

Prototipos rápidos internos sin consumidores externos (la versificación fechada será adecuada).
Datos/modelos con fichas experimentales (mejor Model/Schema Versioning con compatibilidad a nivel de convertidor).
Paquetes de contenido sin API pública estable.

17) Conclusión

SemVer es un contrato de confianza entre el fabricante y el consumidor. Defina claramente lo que rompe la compatibilidad, automatice el reconocimiento de tipos de lanzamientos y la publicación de artefactos, mantenga un CHANGELOG transparente y cumpla con la política de privatizaciones. Entonces, las actualizaciones se volverán rutinarias, previsibles y seguras - y la infraestructura y las APIs se desarrollarán sin sobresaltos para las empresas.