Release e Versionamento¶
Este documento define um padrão simples e direto para versionar releases na Arkorizon.
O objetivo é manter rastreabilidade sem burocracia. A regra deve ser fácil de aplicar em APIs, serviços, agents, bibliotecas, SDKs e documentações.
Padrão¶
Use Semantic Versioning no formato:
MAJOR.MINOR.PATCH
Exemplos:
1.0.0
1.1.0
1.1.1
2.0.0
Quando alterar cada número¶
| Parte | Quando usar | Exemplo |
|---|---|---|
MAJOR |
Mudança incompatível ou quebra de contrato. | 1.8.0 -> 2.0.0 |
MINOR |
Nova funcionalidade compatível. | 1.8.0 -> 1.9.0 |
PATCH |
Correção, ajuste pequeno ou melhoria compatível. | 1.8.0 -> 1.8.1 |
Regra prática¶
Use PATCH quando:
- corrigir bug;
- ajustar comportamento sem quebrar contrato;
- corrigir documentação publicada junto do produto;
- melhorar performance sem alterar contrato;
- corrigir configuração ou pipeline sem mudar funcionalidade.
Use MINOR quando:
- adicionar endpoint compatível;
- adicionar campo opcional;
- adicionar funcionalidade nova;
- adicionar suporte a novo cenário sem quebrar uso existente.
Use MAJOR quando:
- remover endpoint;
- remover campo usado por clientes;
- mudar contrato de API de forma incompatível;
- alterar comportamento esperado de forma quebradora;
- exigir migração obrigatória para continuar usando o produto.
Tags Git¶
Toda release deve ter tag Git com prefixo v.
v1.0.0
v1.1.0
v1.1.1
v2.0.0
Comando:
git tag -a v1.1.0 -m "Release v1.1.0"
git push origin v1.1.0
Relação com commits¶
Commits semânticos ajudam a decidir a próxima versão.
| Tipo de mudança | Versão sugerida |
|---|---|
fix |
PATCH |
perf |
PATCH |
security compatível |
PATCH |
feat |
MINOR |
BREAKING CHANGE ou ! |
MAJOR |
O formato de commit fica em Commit Semântico.
Versionamento de APIs¶
APIs devem ter versão no caminho público.
/api/v1/auth/login
/api/v1/users
/api/v1/projects
Use v1 enquanto as mudanças forem compatíveis.
Crie v2 quando houver quebra de contrato.
/api/v2/auth/login
Não crie v2 para qualquer mudança. Prefira evoluir v1 com mudanças compatíveis.
Versionamento de artefatos¶
Artefatos publicados devem usar a mesma versão da release.
Maven:
<version>1.1.0</version>
Docker:
ghcr.io/arkorizon/arkorizon-iam-auth-service:1.1.0
SDK:
arkorizon-java-sdk:1.1.0
Changelog simples¶
Toda release relevante deve ter um resumo claro.
Formato recomendado:
## v1.1.0
### Added
- Add refresh token rotation.
### Fixed
- Normalize email before authentication.
### Changed
- Improve token expiration validation.
Use apenas seções que fizerem sentido.
Release notes¶
Release notes devem explicar impacto de forma objetiva.
Inclua:
- o que mudou;
- por que mudou;
- impacto positivo;
- breaking changes, se houver;
- instruções de migração, se houver.
Exemplo:
## Release v1.1.0
Adds refresh token rotation to improve authentication security.
No breaking changes.
Hotfix¶
Hotfix normalmente gera PATCH.
Atual: v1.1.0
Correção: fix(auth): correct token expiration validation
Nova: v1.1.1
O padrão de nome da branch de hotfix fica em Branch Naming.
Regra final¶
Versionamento deve responder uma pergunta simples:
Essa mudança corrige, adiciona ou quebra algo?
- Corrige:
PATCH. - Adiciona sem quebrar:
MINOR. - Quebra contrato:
MAJOR.