Versionamento e release¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06

Fontes de versão¶

Lugar	O que representa	Quem atualiza
gradle.properties `version=X.Y.Z`	Versão do projeto (SemVer)	Manual no bump
CHANGELOG.md	Histórico legível de mudanças	Manual no bump
Tag Git `vX.Y.Z`	Snapshot imutável da release	Manual no bump
src/main/resources/application.yml `openapi.info.version`	Versão do contrato HTTP (`/api/**`)	Manual só quando há breaking change na API REST
Env `SENTRY_RELEASE` (Coolify)	Tag de release nos eventos Sentry	Manual no Coolify ao fazer deploy

Decisão de design: openapi.info.version é desacoplado do project.version. A versão da API REST tem semântica própria — só sobe quando o contrato HTTP quebra (endpoint removido, schema de body alterado de forma incompatível, etc.). Mudanças internas do app (UI, refactor, login) não mexem nela.

Convenção de commits¶

Conventional Commits leve (já em uso no projeto):

feat: ... — nova funcionalidade → minor bump
fix: ... — correção de bug → patch bump
chore: ..., docs: ..., test: ..., refactor: ... — sem bump (a menos que acumule)
feat!: ... ou BREAKING CHANGE: no corpo → major bump

Decisão do tipo de bump (SemVer)¶

Versão atual: 1.0.0. Regras SemVer canônicas (post-1.0):

Mudança	Bump	Exemplo
Bug fix	patch	`1.0.0 → 1.0.1`
Feature compatível	minor	`1.0.0 → 1.1.0`
Breaking change (API REST quebrada, schema DB incompatível, env obrigatória nova)	major	`1.0.0 → 2.0.0`

Processo de release (passo-a-passo)¶

Suponha que vai sair da 1.0.0 para 1.1.0 (minor bump com feat: ...).

1. Branch limpa¶

git switch master
git pull --ff-only
git status     # tem que estar limpo

(Ou, se a release sai de uma feature branch antes do merge, faça o bump na branch e merge — o processo é o mesmo.)

2. Atualizar `gradle.properties`¶

version=1.1.0

3. Atualizar `CHANGELOG.md`¶

Mover entradas de [Unreleased] para uma nova seção [1.1.0] - YYYY-MM-DD (data de hoje).
Limpar [Unreleased] (deixar vazio para o próximo ciclo).

Atualizar os links de comparação no rodapé:

[Unreleased]: https://fonte.xadm.biz/xadm/integrador-server/compare/v1.1.0...HEAD
[1.1.0]: https://fonte.xadm.biz/xadm/integrador-server/compare/v1.0.0...v1.1.0
[1.0.0]: https://fonte.xadm.biz/xadm/integrador-server/compare/v0.1.0...v1.0.0

4. Commit + tag¶

git add gradle.properties CHANGELOG.md
git commit -m "chore(release): v1.1.0"
git tag -a v1.1.0 -m "v1.1.0 - <descrição curta>"
git push origin master
git push origin v1.1.0

5. Atualizar Sentry release no Coolify (opcional)¶

No painel do Coolify, app de cada cliente: - Atualizar a env SENTRY_RELEASE=v1.1.0 (ou integrador@1.1.0 se preferir). - Redeploy.

Eventos no Sentry passam a ser tagueados com a versão — facilita correlacionar erros com release.

6. (Opcional) Atualizar `openapi.info.version`¶

Apenas se houve breaking change na API REST. Bump em separado, sem sincronizar com project.version. Ver tabela no topo.

Como saber o que entrou desde a última release¶

git log --oneline v1.0.0..HEAD

Use o output para preencher o CHANGELOG. Convenção: agrupar por tipo (Added / Changed / Fixed / Security) — ler o type: do conventional commit ajuda.

Como inspecionar a versão em runtime¶

A versão do projeto não vai automaticamente para o JAR (o artefato chama-se app.jar sem versão). Hoje, para confirmar a versão de um deploy, use:

Tag git do commit deployado (Coolify mostra o SHA do deploy → git tag --points-at <sha>).
Env SENTRY_RELEASE no painel do Coolify.
Log de startup do Sentry: Sentry inicializado (environment=production) — o release aparece como tag nos eventos.

Futuro (opcional, não implementado): expor project.version via um endpoint /version ou no log de startup do app. Adicionar quando virar dor.

Notas históricas¶

O bump de 0.1 → 1.0.0 (release de 2026-05-19) marcou a primeira release com processo formal: introdução do login Google, CHANGELOG, tag git e doc neste arquivo. Antes disso, o version="0.1" em build.gradle.kts era apenas informativo e nunca foi incrementado.