# Estratégia de Versionamento e Guia de Release

> **Diretrizes de Versionamento Semântico (SemVer 2.0.0), Metas de Qualidade JaCoCo e Roteiro de Corte da Tag v0.1.0**

Este documento detalha as convenções de versionamento do **CyberCore Signer**, o ciclo de vida dos artefatos Maven/SDK e o procedimento operacional padrão para lançamento de novas versões e tags.

---

## 1. Política de Versionamento Semântico (SemVer 2.0.0)

O projeto adota a especificação [SemVer 2.0.0](https://semver.org/lang/pt-BR/) no formato `MAJOR.MINOR.PATCH`:

```
v{MAJOR}.{MINOR}.{PATCH}
Exemplo: v0.1.0, v0.2.0, v1.0.0
```

### Critérios de Incremento

| Componente | Quando Incrementar | Exemplos no CyberCore Signer |
|---|---|---|
| **MAJOR** (`X.0.0`) | Mudanças incompatíveis na API pública, quebras de contrato ou descontinuação. | Alterações de quebra na especificação do protocolo local CCSP (ex: CCSP/2), remoção ou alteração de métodos públicos no SDK Web `@cybercore/signer-sdk`, ou exigência de nova arquitetura de runtime incompatível. |
| **MINOR** (`0.X.0`) | Novas funcionalidades retrocompatíveis e adições de arquitetura. | Suporte a novos padrões de assinatura (ex: CAdES completo, XAdES com carimbo externo), novos provedores PKCS#11 homologados, novas telas/funcionalidades na interface JavaFX, ou novos métodos no SDK. |
| **PATCH** (`0.0.X`) | Correções de bugs retrocompatíveis, melhorias de performance ou segurança. | Ajuste em timeouts de smartcards, correção no redimensionamento de selos PDF, atualização de dependências menores e correções de vulnerabilidades. |

---

## 2. Metas de Qualidade e Plano de Aumento de Cobertura (JaCoCo)

O projeto aplica a meta `jacoco:check` vinculada à fase `verify` em cada módulo Maven. Os limites foram calibrados com base na medição real do projeto e possuem um cronograma progressivo de incremento:

### Matriz de Limites e Metas de Cobertura

| Módulo | Cobertura Medida (v0.1.0) | Limite Atual (`jacoco:check`) | Meta v0.2.0 | Meta Alvo v1.0.0 |
|---|---|---|---|---|
| **`cybercore-core`** | 65.0% linhas / 44.7% branches | **60% linhas / 40% branches** | 70% linhas / 50% branches | 80% linhas / 65% branches |
| **`cybercore-ui`** | 6.1% linhas / 11.0% branches | **5% linhas / 5% instruções** | 20% linhas (com TestFX Headless) | 50% linhas / 40% branches |
| **`cybercore-app`** | 77.7% linhas / 52.0% branches | **70% linhas / 45% branches** | 80% linhas / 55% branches | 85% linhas / 70% branches |

### Plano de Ação para Expansão
1. **Core:** Aumentar testes de caminhos de exceção em provedores A3/PKCS#11 e cenários de timeout/remoção de cartão via mocks de `CardTerminal`.
2. **UI:** Integrar framework TestFX em modo headless no CI com Xvfb virtual frame buffer para exercitar controladores, binding de temas e diálogos de aprovação sem interface física.
3. **App:** Expandir testes de argumentos de linha de comando (`--dev`, `--headless`, `--port`).

---

## 3. Passo a Passo para Criar a Primeira Tag `v0.1.0`

> **IMPORTANTE:** Este procedimento é documentado para execução pela equipe de governança/release. **Não execute a criação da tag automaticamente.**

### Pré-requisitos
* Branch `main` atualizada e com pipeline de CI verde no Gitea Actions.
* Árvore de trabalho limpa (`git status` sem alterações pendentes).
* Ambiente com JDK 25 LTS ativo.

---

### Procedimento Operacional

#### Passo 1: Executar validação rigorosa local
```bash
JAVA_HOME="${HOME}/.jdks/jdk-25.0.4.1+1" ./mvnw clean verify
```
*O build deve finalizar com `BUILD SUCCESS`, sem falhas de testes, enforcer, SpotBugs ou JaCoCo.*

#### Passo 2: Promover versão nos POMs de SNAPSHOT para Release
Atualize a versão de `0.1.0-SNAPSHOT` para `0.1.0` em todos os módulos:
```bash
./mvnw versions:set -DnewVersion=0.1.0 -DgenerateBackupPoms=false
```

#### Passo 3: Sincronizar versão no SDK JavaScript
```bash
cd sdk
npm version 0.1.0 --no-git-tag-version
cd ..
```

#### Passo 4: Atualizar data e cabeçalhos no `CHANGELOG.md`
Edite o arquivo [CHANGELOG.md](../CHANGELOG.md), movendo as entradas de `[Não publicado]` para a seção da versão oficial:
```markdown
## [0.1.0] - 2026-10-20
```

#### Passo 5: Realizar o commit de Release
```bash
git add pom.xml modules/*/pom.xml sdk/package.json CHANGELOG.md
git commit -m "chore(release): prepare release v0.1.0"
```

#### Passo 6: Criar a tag Git anotada
Crie a tag anotada com mensagem formal de lançamento:
```bash
git tag -a v0.1.0 -m "Release v0.1.0: versão inicial do CyberCore Signer com suporte A1/A3, PAdES, XMLDSig e CCSP/1"
```

#### Passo 7: Enviar o commit e a tag para o repositório remoto
```bash
git push origin main
git push origin v0.1.0
```

#### Passo 8: Avançar a versão de desenvolvimento para o próximo ciclo
Logo após o push da tag de release, prepare a base para os próximos desenvolvimentos:
```bash
# Avança para o próximo ciclo de patch ou minor (ex: 0.1.1-SNAPSHOT):
./mvnw versions:set -DnewVersion=0.1.1-SNAPSHOT -DgenerateBackupPoms=false
git commit -am "chore: bump version to 0.1.1-SNAPSHOT"
git push origin main
```