86cbe8e431
- Implementa versionamento semântico para imagens Docker - Adiciona job de release automática no GitHub Actions - Releases criadas apenas para tags na branch main - Adiciona documentação de versionamento em docs/VERSIONAMENTO.md - Suporte a tags semânticas (v0.1.0, v0.5.0, etc) - Versionamento baseado em package.json e tags Git
128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# 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
|
|
|