111 lines
5.0 KiB
Markdown
111 lines
5.0 KiB
Markdown
# 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
|
|
```
|