Versionização semântica

Semantic Versioning (SemVer) - Um contrato sobre como o número de versão reflete a natureza das mudanças. Formato: MAJOR. MINOR. PATCH[-PRERELEASE][+BUILD].

• MAJOR - Alterações incompatíveis (breaking).
• MENOR - Fichas/extensões reversíveis.
• PATCH - Correções de erro/segurança invertidas.

Objetivo: previsível evolução da API, eventos, esquemas de dados, SDK e configs sem falhas repentinas dos consumidores.

1) Convenção de números

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

Pré-release - Montagens instáveis; não prometem compatibilidade.
Build metadata ('+ sha') - não afeta a ordem de comparação, é útil para o rastreamento.
Até 1. 0. 0 qualquer alteração pode ser considerada breaking (mas é melhor cumprir as regras desde o início).

2) O que contar breaking/menor/patch

• Registo e segurança sem mudança de contrato.
• Docas-update que não se importam com o contrato.
• Otimizar sem alterar respostas/eventos/diagramas.

• Adicione novos campos/métodos/endpoint opcionais.
• Extensão enum com valores se os consumidores são tolerantes com valores desconhecidos.
• Novos índices de base de dados, colunas nullable com default, novos eventos adicionais aos antigos.

• Remover/renomear campos, alterar tipos, obrigatoriedade.
• Altera semântica/status/código de erro.
• Altere o formato de seriado, o padrão de chaves, o protocolo de transporte.
• Compactação/fusão de topics, transferência do significado do evento, alteração do padrão de partilha.
• Migração de base de dados que exigem alternância de dois fases sem compatibilidade invertida.

3) Versionização por artefatos

3. 1 REST

As opções são 'URI/v1/...', cabeçalhos ('Accept: aplicação/vnd. acme. game+json; versão = 1 '), parâmetro.
Recomendação: versão em URI para API públicas; para o interior - através do título c negotificação.
MENOR: adição de campos opcionais, novos filtros/recursos; não altere as respostas existentes.
PATCH: capturas, especificação de descrições, arrumações estáveis.

3. 2 gRPC

Mudar assinaturas/tipos de → MAJOR (novo pacote/serviço: 'acme. wallet. v2`).
Novos campos com marca optional; o servidor deve ignorar os desconhecidos.
Não removemos os campos: «depriceite + reservar número», e só removemos no seguinte MAJOR.

3. 3 GraphQL

MENOR: novos campos/tipos/query; remoção através de '@ deprecated' + janela de migração, remoção completa - MAJOR.
Alterar o nullable→non -nullable - MAJOR.

3. 4 Eventos e topics (Kafka/SQS)

Esquemas em Schema Registry: Evolução aditiva (adicionar campos com default).
Uma nova versão incompatível → um novo subject/topic ('bet. settled. v2`).
A chave de partilha está inalterada dentro do MAJOR.

3. 5 Circuitos de Base de Dados

1. Adicionar coluna (nullable/com default) →

2. Preencher backfill →

3. Traduzir leitura de →

4. Remover o antigo (somente no MAJOR).

Alteração do tipo/RC/exclusividade - MAJOR, debaixo de um fichiflag e uma gravação dupla.

3. 6 SDK/CLI

Métodos públicos/assinaturas são as mesmas regras.
Para a generação automática (OpenAPI/Proto) - versão do nome de lote e artefatos.

4) Política de despricagem e ciclo de vida

Cada alteração de breaking é precedida de uma despricagem (normalmente 90-180 dias para o exterior, 30-60 para o interior).
Comunicações: changelog, e-mail/webhooks para parceiros, banners no portal do desenvolvedor.
Modo dual-run: Paralelamente, mantemos 'v1' e 'v2', monitoriando a parte do tráfego 'v1'.
Sunset headers (REST): `Sunset: 2026-03-31`, `Link: <url>; rel="deprecation"`.

5) Version negotiation

O cliente envia uma versão desejável + máxima suportada (por exemplo, 'Accept-Version: 1,2').
O servidor responde por 'Conteúdo-Versão: 2' se for capaz de aumentar.
Os protocolos bidirecionais (WebSocket, gRPC) incluem a troca de quadros Hello com 'suported _ versions'.

6) Integração com adaptadores de provedores (LCA)

O provedor externo altera o padrão - dentro do adaptador, mantemos os geradores v1/v2 e lançamos o MENOR para o evento interno, mantendo o nosso contrato de domínio.
Se as alterações externas conseguirem entrar é o MAJOR do nosso evento de domínio e o novo subject.

7) Changelog e marcas de commitas

• `feat:...` → MINOR
• 'fix:... '/' chore', 'docs',' perf '(sem contrato) →' PATCH '
• 'feat!: '/' fix!: '/' refator!:' ou 'BREAKING MUDANÇA:' no corpo → MAIOR

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

8) Automação de lançamentos

CI: Validadores de circuitos (OpenAPI/Protobuf/Avro/JSON-Schema), detecção breaking-difs.
SemVer-bot: Análise do Conventional Commits → calcula bump (major/menor/patch), exibe a marca, gera changelog.
CD: deploy e release separados (fichicheflags/configs ativam a nova versão).
Controle: não publicamos 'latest' em PRO antes de canary de sucesso e SLO alinhado.

9) Semântica para configurações e políticas

Configs (YAML/JSON) também têm uma versão do esquema: 'schema _ versão: 3'.
MENOR - novos campos/regras opcionais; MAJOR - mudança de estrutura/obrigatoriedade.
Suporte v2/v3 no validador; migrador de configs com relatório de incompatibilidade.

10) Testes de compatibilidade

Consumer-driven contracts (Pact): para cada integração.
Schema-evolution tests: execute os velhos payload's no novo padrão e vice-versa.
Replay: reprodução do tráfego de prod 'v1' em 'v2' na sombra.
Property-based: resistência a campos desconhecidos/enum.

11) Observabilidade por versão

Selecione as métricas/logs: 'api _ versão', 'schema _ version', 'event _ version'.
Dashboards de migração: proporção de tráfego em versões, erro/latência em 'v1/v2'.
Alerts: Se 'v1' não baixar como planeado; 4xx/5xx após o lançamento de 'v2'.

12) Patternos migratórios sem interrupções

Expand → Migrate → Contract (БД).
Dual write + compara as divergências antes de mudar de leitura.
Shadow compare para classificação/regras.
Canary por tenentes/regiões; função flags para saques rápidos.
Read-composat/Write-compat da janela: A nova versão lê dados antigos, mas escreve em um novo formato.

13) Anti-pattern

Versão em cada campo em vez de versionizar o recurso/evento.
Alterações de breaking escondidas sob MINOR (por exemplo, alteração de default).
Remove o despricado sem janela e sem métricas de consumo.
«Para sempre v1»: falta de um plano para remover versões antigas de tecnologia → e vulnerabilidade.
Mistura versão empresarial e versão de contêiner.

14) Folha de cheque da política de versionização

• O formato da versão e as fontes da verdade (Registry/Portal) foram registrados.
• A lista de critérios breaking de artefatos (REST/gRPC/GraphQL/events/DB) foi aprovada.
• Processo de despricagem: prazos, comunicações, sunset/banners, dual-run.
• Cheque de Diff automático e Convenional Commits.
• Dashboards de consumo de versões e alertas.
• Playbooks de migração (expand/migrate/contract, dual-write, shadow).
• Configs e SDK têm suas próprias versões e maiúsculas.
• Documentação «como selecionar uma versão» para os clientes e «como aumentar» para os comandos.

15) Exemplos de versionização (maletas iGaming)

O evento 'BetSettled v1' → 'v2' adicionou 'void _ reason' (optional) e 'tax'. amount` (optional) — MINOR. Transferir 'payout'→'win_amount' - MAJOR, novo subject.
REST '/wallets/transfer ': adicionaram filtro'? tenant _ id = '- MENOR. Alterou o código de erro '409'→'422' - MAJOR.
GraphQL: Marcaram 'Player. age 'como' @ deprecated 'a favor de' Player. ageGroup '- lançamento em MENOR, remoção em MAIOR após o período X.
BD: Adicionaram a coluna 'bónus _ wager _ left' nullable - MENOR. Fizeram "non-null" e removeram "bónus _ left' - MAJOR (via expand/contract).

Conclusão

A versionização semântica não é sobre números, é sobre confiança e previsibilidade. Regras claras, verificações automáticas, despricagens controladas e telemetria transparente permitem a evolução da API, eventos e esquemas sem dor para as integrações - e liberar mudanças frequentemente, de forma segura e sensata.