Versificación semántica

Semantic Versioning (SemVer) es un contrato sobre cómo el número de versión refleja la naturaleza de los cambios. Formato: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - Cambios incompatibles (breaking).
• MINOR - fiches/extensiones a la inversa.
• PARCHE: correcciones de errores/seguridad a la inversa.

Objetivo: evolución predecible de API, eventos, esquemas de datos, SDK y configuraciones sin roturas repentinas de los consumidores.

1) Convenio de números

X.Y.Z[-alpha.1    -rc.1][+build.sha]

Pre-lanzamiento ('-alpha', '-beta', '-rc') son conjuntos inestables; no prometen compatibilidad.
Construir metadata ('+ sha'): no afecta al orden de comparación, es útil para el rastreo.
Hasta 1. 0. 0 cualquier cambio puede considerarse breaking (pero es mejor respetar las reglas desde el principio).

2) Qué contar breaking/minor/patch

• Fixes de errores y seguridad sin cambio de contrato.
• Dock-updates que no afectan al contrato.
• Optimizaciones sin cambios en las respuestas/eventos/esquemas.

• Agregar nuevos campos/métodos/endpoints opcionales.
• Extensión enum valores si los consumidores son tolerantes a valores desconocidos.
• Nuevos índices de DB, altavoces nullables con default, nuevos eventos adicionales a los antiguos.

• Eliminar/cambiar el nombre de los campos, cambiar tipos, obligatoriedad.
• Cambiar la semántica/estados/códigos de error.
• Cambio de formato de serialización, esquema de claves, protocolo de transporte.
• Comprimir/combinar topics, transferir el significado del evento, cambiar el esquema de partición.
• Migraciones de DB que requieren conmutación «bifásica» sin compatibilidad inversa.

3) Versificación por artefactos

3. 1 REST

Opciones: 'URI/v1/...', títulos ('Accept: application/vnd. acme. game+json; version = 1 '), parámetro.
Recomendación: versión en URI para API públicas; para el interior - a través del encabezado c negotiation.
MENOR: agregar campos opcionales, nuevos filtros/recursos; no cambie las respuestas existentes.
PARCHE: fijos, refinamiento de descripciones, ordenaciones estables.

3. 2 gRPC

Cambio de firmas/tipos de → MAJOR (nuevo paquete/servicio: 'acme. wallet. v2`).
Nuevos campos: con la etiqueta optional; el servidor debe ignorar las incógnitas.
Los campos no se eliminan: «Despricate + Reservar número», eliminar - sólo en el siguiente MAJOR.

3. 3 GraphQL

MINOR: nuevos campos/tipos/query; eliminación - vía '@ deprecated' + ventana de migración, eliminación completa - MAYOR.
Cambiar nullable→non -nullable - MAYOR.

3. 4 Eventos y topics (Kafka/SQS)

Esquemas en el Registro Schema: evolución additive (añadir campos con impagos).
La nueva versión incompatible → el nuevo subject/topic ('bet. settled. v2`).
La clave de partición no se modifica dentro de MAJOR.

3. 5 Esquemas de DB

1. Añadir una columna (default nullable/c) →

2. Rellenar el backfill →

3. Traducir lecturas →

4. Quitar el viejo (sólo en MAJOR).

Cambio de tipo/RC/Singularidades - MAYOR, bajo flagelo y doble registro.

3. 6 SDK/CLI

Métodos/firmas públicas - las mismas reglas.
Para autogeneración (OpenAPI/Proto): versión de nombre por lotes y artefactos.

4) Política de desproporción y ciclo de vida

Cada cambio de breaking está precedido por una despricación (normalmente 90-180 días para los externos, 30-60 para los internos).
Comunicaciones: changelog, e-mail/webhooks a los socios, banners en el portal del desarrollador.
Modo dual-run: en paralelo mantenemos el 'v1' y el 'v2', la fracción de tráfico 'v1' es monitorable.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

El cliente envía la versión deseada + máxima soportada (por ejemplo, 'Accept-Version: 1,2').
El servidor responde a 'Content-Version: 2' si ha podido aumentar.
En protocolos bidireccionales (WebSocket, gRPC): intercambio de marcos Hello con 'supported _ versions'.

6) Integración con adaptadores de proveedores (ACL)

El proveedor externo cambia el esquema - dentro del adaptador sostenemos los mappers v1/v2 y liberamos MINOR para el evento interno, manteniendo nuestro contrato de dominio.
Si los cambios externos se perforan hacia adentro es el MAJOR de nuestro evento de dominio y el nuevo subject.

7) Changelog y etiquetas de commita

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs',' perf '(sin contrato) → PATCH
• 'feat!: '/' fix!: '/' refactor!:' o'BREAKING CHANGE: 'en el cuerpo → MAYOR

[2.3.0] - 2025-10-31
Added
- GET /v1/games?capabilities=jackpot (optional)
Changed
- GraphQL: field Game.volatility @deprecated, use Game.riskProfile

8) Automatización de lanzamientos

CI: validadores de circuitos (OpenAPI/Protobuf/Avro/JSON-Schema), el detalle de los diffs de breaking.
SemVer-bot: análisis Conventional Commits → calcula bump (mayor/menor/patch), coloca la etiqueta, genera changelog.
CD: deploy y release separados (fichflags/confites activan la nueva versión).
Control: no publicamos 'latest' en PRO antes de un canario exitoso y un SLO negociado.

9) Semántica para configuraciones y políticas

Las configuraciones (YAML/JSON) también tienen una versión del esquema: 'schema _ version: 3'.
MINOR: nuevos campos/reglas opcionales; MAJOR - Cambio de estructura/obligatoriedad.
Soporte v2/v3 en el validador; migrador de configuraciones con informe de incompatibilidades.

10) Pruebas de compatibilidad

Consumer-driven contracts tests: por cada integración.
Pruebas de evolución de Schema: corriendo viejos payload's en el nuevo esquema y viceversa.
Replay: reproducir tráfico prod 'v1' en 'v2' a la sombra.
Property-based: resistencia a campos/enum desconocidos.

11) Observabilidad por versiones

Etiquete métricas/logs: 'api _ version', 'schema _ version', 'event _ version'.
Dashboards de migración: proporción de tráfico por versión, error/latencia por 'v1/v2'.
Alertas: si 'v1' no desciende según el plan; crecimiento 4xx/5xx después de la liberación de 'v2'.

12) Patrones de migración sin tiempo de inactividad

Expand → Migrate → Contract (БД).
Escritura dual + comparación de divergencias antes de cambiar de lectura.
Compare Shadow para clasificar/reglas.
Canario por tenantes/regiones; flags de función para retrocesos rápidos.
Ventana Read-compat/Write-compat: la nueva versión lee datos antiguos, pero escribe en un nuevo formato.

13) Anti-patrones

«Versión en cada campo» en lugar de versionar el recurso/evento.
Cambios de breaking ocultos bajo MINOR (por ejemplo, modificación de impagos).
Elimina el despeñado sin ventana y las métricas de consumo.
«Forever v1»: ausencia de un plan para eliminar versiones antiguas → tehdolg y vulnerabilidad.
Mezcla de la versión empresarial y la versión de la imagen contenedora.

14) Lista de comprobación de la política de versionamiento

• El formato de las versiones y las fuentes de la verdad (Registro/Portal) están fijos.
• Se aprobó una lista de criterios de breaking por artefactos (NAT/gRPC/GraphQL/events/DB).
• Proceso de Despricaciones: plazos, comunicaciones, sunset/banners, dual-run.
• Comprobador automático de circuitos diff y Comités Conventuales.
• Dashboards de consumo de versiones y alertas.
• Playbucks de migración (expand/migrate/contract, dual-write, shadow).
• Las configuraciones y SDK tienen sus propias versiones y registros.
• Documentación «cómo seleccionar una versión» para los clientes y «cómo aumentar» para los comandos.

15) Ejemplos de versionamiento (casos de iGaming)

Evento 'BetSettled v1' → 'v2': ha añadido 'void _ reason' (optional) y 'tax. amount` (optional) — MINOR. Reasignaciones 'payout'→'win_amount' - MAYOR, nuevo subject.
NAT '/wallets/transfer ': ha añadido el filtro'? tenant _ id = '- MINOR. Ha cambiado el código de error '409'→'422' - MAJOR.
GraphQL: etiquetó 'Player. age 'as' @ deprecated 'a favor de' Player. ageGroup '- liberación en MINOR, eliminación en MAJOR después del período X.
DB: agregaron la columna 'bonus _ wager _ left' nullable - MINOR. No se hizo nulo y se eliminó 'bonus _ left' - MAJOR (a través de expand/aprox).

Conclusión

La versificación semántica no se trata de números, sino de credibilidad y previsibilidad. Reglas claras, verificaciones automáticas, despricaciones controladas y telemetría transparente permiten que las API, eventos y circuitos evolucionen sin dolor para integraciones - y liberen cambios con frecuencia, de forma segura y significativa.