From 4e6dd2a02919c22ddbe70eb8d858d78629f7696e Mon Sep 17 00:00:00 2001 From: Claudecio Martins Date: Tue, 20 Oct 2026 14:36:41 -0300 Subject: [PATCH] docs: document semantic versioning strategy and v0.1.0 release guide --- docs/README.md | 2 + docs/release-and-versioning.md | 110 +++++++++++++++++++++++++++++++++ renovate.json | 1 - 3 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/release-and-versioning.md diff --git a/docs/README.md b/docs/README.md index b2e5e3e..8251b27 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,6 +37,7 @@ Se você precisa implantar, homologar ou validar os aspectos de conformidade e s * **[Modelo de Segurança e Privacidade](security.md):** Diretrizes de menor privilégio, proteção contra CSRF e DNS Rebinding, descarte seguro de senhas e PIN em memória e conformidade com a LGPD. * **[Instalação e Empacotamento Nativo](installation.md):** Criação de instaladores autocontidos para Windows (MSI/EXE) via `jpackage`, requisitos do sistema e parâmetros de instalação corporativa silenciosa. +* **[Estratégia de Versionamento e Release](release-and-versioning.md):** Padrão SemVer 2.0.0, plano progressivo de cobertura JaCoCo e roteiro para corte da primeira tag v0.1.0. * **[Diagnóstico e Troubleshooting](diagnostics.md):** Subsistema de auto-teste, checklist de integridade de runtime e guia de resolução de problemas comuns de hardware/middleware. * **[Limitações Técnicas Declaradas](limitations.md):** Declaração formal de requisitos de drivers, limitações de hardware mono-thread e dependências de sistema operacional (em conformidade com a Regra 23 do projeto). @@ -56,6 +57,7 @@ Se você precisa implantar, homologar ou validar os aspectos de conformidade e s | [`security.md`](security.md) | Políticas de isolamento, memória e privacidade | Segurança & Compliance | | [`diagnostics.md`](diagnostics.md) | Auto-testes e guia de resolução de problemas | Suporte & Operações | | [`installation.md`](installation.md) | Empacotamento com `jpackage` e instaladores MSI | DevOps & Usuários Finais | +| [`release-and-versioning.md`](release-and-versioning.md) | Estratégia SemVer, metas JaCoCo e corte de tags | DevOps & Governança | | [`limitations.md`](limitations.md) | Dependências de drivers e limitações declaradas | Todos | | [`development-mode.md`](development-mode.md) | Parâmetro `--dev` e certificados de teste | Desenvolvedores Desktop | | [`sdk.md`](sdk.md) | Guia completo da biblioteca JavaScript | Desenvolvedores Web | diff --git a/docs/release-and-versioning.md b/docs/release-and-versioning.md new file mode 100644 index 0000000..9e5b5d7 --- /dev/null +++ b/docs/release-and-versioning.md @@ -0,0 +1,110 @@ +# 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 +``` diff --git a/renovate.json b/renovate.json index 8bc6d80..3761339 100644 --- a/renovate.json +++ b/renovate.json @@ -4,7 +4,6 @@ "extends": [ "config:recommended" ], - "platform": "gitea", "dependencyDashboard": true, "semanticCommits": "enabled", "commitMessagePrefix": "chore(deps):",