portalweb-api/docs/VERSIONAMENTO.md

Sistema de Versionamento

Este documento descreve o sistema de versionamento utilizado no projeto, incluindo como as imagens Docker são versionadas e como criar releases no GitHub.

Visão Geral

O projeto utiliza versionamento semântico baseado no arquivo package.json e tags Git para gerenciar versões de imagens Docker e releases no GitHub Container Registry (GHCR).

Versionamento de Imagens Docker

As imagens Docker são automaticamente versionadas durante o processo de CI/CD baseado no contexto do push:

Branches

• Branch homologacao: ghcr.io/usuario/repo:homologacao
• Branch main:
  • ghcr.io/usuario/repo:main
  • ghcr.io/usuario/repo:latest
  • ghcr.io/usuario/repo:{versao-do-package.json}

Tags Git

Quando uma tag é criada (formato v*, exemplo: v0.1.0), as seguintes tags são geradas:

• ghcr.io/usuario/repo:0.1.0 (versão completa)
• ghcr.io/usuario/repo:0.1 (major.minor)
• ghcr.io/usuario/repo:0 (major)

Commits

Cada commit gera uma tag com o SHA do commit:

• ghcr.io/usuario/repo:{branch}-{sha}

Releases no GitHub

Releases são criadas automaticamente quando uma tag Git no formato v* é enviada para a branch main. O processo inclui:

1. Verificação se a tag está na branch main
2. Geração automática de changelog baseado nos commits desde a última tag
3. Criação da release no GitHub com:
   • Nome da versão
   • Changelog completo
   • Instruções para download da imagem Docker

Como Criar uma Nova Versão

Para Homologação

1. Atualize a versão no package.json:

npm version patch  # Incrementa patch: 0.0.1 -> 0.0.2
npm version minor  # Incrementa minor: 0.0.1 -> 0.1.0
npm version major  # Incrementa major: 0.0.1 -> 1.0.0

2. Faça commit e push:

git add package.json package-lock.json
git commit -m "chore: bump version to 0.1.0"
git push origin homologacao

A imagem Docker será automaticamente buildada e publicada com a tag correspondente à branch.

Para Produção (Release)

1. Faça merge da branch homologacao para main:

git checkout main
git merge homologacao

2. Crie uma tag e faça push:

git tag v0.1.0
git push origin main --tags

Este processo irá:

• Buildar a imagem Docker com as tags de versão semântica
• Criar automaticamente uma release no GitHub
• Publicar a imagem no GitHub Container Registry

Verificar Versão Atual

A versão atual do projeto está definida no arquivo package.json:

{
  "version": "0.0.1"
}

Estrutura de Tags Docker

As imagens Docker seguem o seguinte padrão de nomenclatura:

• Desenvolvimento: {registry}/{repo}:{branch-name}
• Versão específica: {registry}/{repo}:{version} (ex: 0.1.0)
• Versão parcial: {registry}/{repo}:{major}.{minor} (ex: 0.1)
• Major version: {registry}/{repo}:{major} (ex: 0)
• Latest: {registry}/{repo}:latest (apenas branch main)
• Commit SHA: {registry}/{repo}:{branch}-{sha}

Workflow de CI/CD

O workflow de CI/CD está configurado no arquivo .github/workflows/ci.yml e executa os seguintes jobs:

1. Lint: Verificação de código e formatação
2. Build: Compilação do projeto TypeScript
3. Test: Execução de testes unitários
4. Test E2E: Execução de testes end-to-end (apenas PRs e main)
5. Docker Build: Build e push da imagem Docker
6. Release: Criação de release no GitHub (apenas tags na main)

Notas Importantes

• Tags devem seguir o formato semântico: v{major}.{minor}.{patch} (ex: v1.0.0)
• Releases são criadas apenas para tags na branch main
• A versão no package.json é usada para versionar imagens em branches
• Tags Git são usadas para versionar imagens em releases de produção