# 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`:

```bash
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:

```bash
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`:

```bash
git checkout main
git merge homologacao
```

2. Crie uma tag e faça push:

```bash
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`:

```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