Versionização semântica

Versionização semântica

1) O que é SemVer e o que é necessário

• MAJOR - Alterações incompatíveis (breaking changes).
• O MENOR é uma nova funcionalidade compatível com API.
• PATCH - Correções de defeitos compatíveis reversíveis.

O objetivo é negociar a estabilidade dos contratos e reduzir o custo das atualizações.

2) Formato de versão

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

`1. 4. 7 'é um lançamento estável.
`1. 5. 0-rc. 2 '- pró-lançamento (release candidate nº 2).
`2. 0. 0+linux. arm64 '- metadados build (não afetam a comparação de versões).

1. Primeiro comparam «MAJOR», depois «MENOR» e «PATCH».

2. Os lançamentos pré são menores do que a versão estável correspondente: '1. 2. 0-rc. 1 < 1. 2. 0`.

3. Os metadados Build ('+...') não afetam a ordem: '1. 2. 0+001 == 1. 2. 0`.

3) O que é considerado uma mudança breaking

• Remover/renomear/alterar a assinatura de métodos públicos/endpoint.
• Altera o formato de logon/saída (padrão JSON, tipos).
• Alterar contratos de erro (códigos/estruturas).
• Altere side-effects/SLAs (por exemplo, limites rigorosos ou novos campos obrigatórios).

Não breaking (quando implementado corretamente): adição de campos opcionais, extensão enum com novos valores (se o cliente ignorá-los), novos endpoints, novas bandeiras de default que não afetam as chamadas atuais.

4) Edições e estratégias de canais

• Marcas: 'alpha', 'beta', 'rc'. Exemplo: '2. 3. 0-beta. 3`.
• Canais: nightly → alpha → beta → rc → stable.
• Política: Os lançamentos pró não devem ser definidos como dependentes transitivos para montagens de prod padrão.

5) Faixas de versão e precisão de dependências

5. 1 Node/npm (SemVer padrão)

`^1. 4. 2` ≈ `>=1. 4. 2 <2. 0. 0 '(autoriza MENOR/PATCH, captando MAJOR).
`~1. 4. 2` ≈ `>=1. 4. 2 <1. 5. 0 '(permite o PATCH dentro do MENOR).
`1. 4. x 'é qualquer pagamento de 1. 4.
Pin exato: '1. 4. 2`.

5. 2 Python (PEP 440, pip)

`~=1. 4. 2` ≈ `>=1. 4. 2,==1. 4.`.
`>=1. 4,<2. 0 '- limites claros.

5. 3 Maven/Gradle (Java)

`[1. 4,2. 0) '- inclusive/exclusivamente.
Recomendação de pina rígida para artefactos críticos de prod.

5. 4 Go modules

Marcas de formatação sempre completas. MINOR. O PATCH ';' v2 + 'requer o sufixo do pod '/v2'.

Recomendação: para aplicativos - pinos exatos (reproducível builds). Para bibliotecas - faixas caret (facilitar atualizações sem quebra).

6) CHANGELOG и Conventional Commits

O registro de alterações estruturado aumenta a transparência.

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` и т. д.
O ponto de exclamação ou bloco 'BREAKING MUDANÇA' anuncia o aumento MAIOR.
CHANGELOG é gerado a partir da história dos commites (release-notas).

7) Política de versionização para API

API pública: SemVer rigorosa; breaking → MAJOR.
HTTP/REST: Versionização por URL/cabeçalho: '/v1/... ', '/v2/...' ou 'Accept: aplicação/vnd. org. service. v2+json`.
Esquemas JSON: extensões menores - novos campos opcionais; major - remover/alterar obrigatórias.
gRPC/Protobuf: Adicione novos campos com novos números; não use números de campos; → remover o deprecate em vez de «quebrar» os existentes.

8) Circuitos de dados e migração

As migrações de base de dados são sincronizadas com as versões do aplicativo: 'app @ 1. 8. 0 'exige' schema @ 1. 8. x`.
Para as alterações de padrão breaking - fases: expand (adicionar), migrate, contract (remover). A versão só aumenta para MAIOR quando você remover um contrato antigo.
Suporte dupla gravação/leitura durante a migração.

9) Monorepo e microsserviços

Multi-package: cada pacote tem o seu 'MAJOR. MINOR. PATCH`; o ciclo geral de raiz dos lançamentos é apenas para meta-artefatos.

• Independent versions (Lerna/Changesets) - aumenta o isolamento.
• Lock-step é mais fácil de comunicar, mas mais falso MAJOR-ov.
• Para os microsserviços, verifique os contratos (OpenAPI/Protobuf) com uma versão diferente: 'contract @ 2. 1. 0 ', o serviço segue-lhe.

10) Automação de lançamentos em 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

Geração de CHANGELOG, publicação de nouts de lançamento, atualização de dependências no GitOps-repo, verificação de que 'principal' sempre indica a última marca estável.

11) Política de despressurização (deprecation policy)

Anúncio: marca a função como deprecated no lançamento MENOR, dê um prazo EOL (por exemplo, 90 dias).
Observabilidade: configure o uso de endpoint obsoletos com contexto user/tenant.
Remover: no seguinte MAJOR. Documente o caminho da migração.

12) Exemplos e modelos

12. 1 Expressão regular de validação de 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 Exemplos de comparação

`1. 2. 3` < `1. 10. 0 '(comparação por MENOR).
`2. 0. 0-rc. 1` < `2. 0. 0`.
`1. 2. 3+build. 5` == `1. 2. 3`.

12. 3 Políticas de Dependências (por exemplo, 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-pattern

Usar 'latest '/marcas de formatação na venda.
Promoção MAJOR sem quebra real («versões de marketing»).
Alterações breaking ocultas sob o disfarce 'PATCH'.
Pré-lançamentos em dependências transitivas de aplicativos de prod.
Alterar o artefato sem uma nova tag (versões mutáveis).
Versões incoerentes do código e do esquema de base de dados.

14) Folha de cheque de implementação (0-45 dias)

0-10 dias

Aceite como padrão obrigatório, aprove os critérios de quebra.
Inclua o Conventional Commits e o modelo PR com o campo 'BREAKING MUDANÇA'.

11 a 25 dias

Ligue o semantic-release/changesets, genérico automático CHANGELOG.
Configure a assinatura e publicação dos artefatos através da tag 'vX. Y.Z`.

26-45 dias

Digite deprecation policy e telemetria de uso de APIs obsoletas.
Sincronize as versões de contratos (OpenAPI/Proto) e serviços.
Proíba 'latest' e marcas de formatação de política (RA/regulamentos CI).

15) Métricas de maturidade

% dos artefactos emitidos apenas pela marca SemVer.
Tempo médio de migração entre as versões MINOR.
O número de incidentes devido a mudanças de breaking ocultas.
Cobertura do Conventional Commits nos repositórios (> 95%).
Proporção de dependências sem faixa flutuante na venda (> 90%).

16) Quando SemVer não é necessário

Protótipos rápidos internos sem consumidores externos (adequado para versionização datada).
Dados/modelos com fichas experimentais (melhor Model/Schema Versioning com compatibilidade ao nível de conversores).
Pacotes de conteúdo sem API pública estável.

17) Conclusão

SemVer é um contrato de confiança entre o produtor e o consumidor. Defina claramente o que rompe a compatibilidade, automatize o reconhecimento de tipos de lançamentos e a publicação de artefatos, mantenha um CHANGELOG transparente e cumpra a política de deprivação. As atualizações serão rotineiras, previsíveis e seguras - e a infraestrutura e a API serão desenvolvidas sem choques para o negócio.