cybercore-signer/docs/release-and-versioning.md

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

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:

./mvnw versions:set -DnewVersion=0.1.0 -DgenerateBackupPoms=false

Passo 3: Sincronizar versão no SDK JavaScript

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, movendo as entradas de [Não publicado] para a seção da versão oficial:

## [0.1.0] - 2026-10-20

Passo 5: Realizar o commit de Release

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:

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

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:

# 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