docs: document semantic versioning strategy and v0.1.0 release guide
This commit is contained in:
Claudecio Martins
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -4,7 +4,6 @@
|
||||
"extends": [
|
||||
"config:recommended"
|
||||
],
|
||||
"platform": "gitea",
|
||||
"dependencyDashboard": true,
|
||||
"semanticCommits": "enabled",
|
||||
"commitMessagePrefix": "chore(deps):",
|
||||
|
||||
Reference in New Issue
Block a user