Guia de Contribuição — CyberCore Signer

Agradecemos o interesse em contribuir com o CyberCore Signer! Para garantir a segurança criptográfica, a estabilidade e a manutenibilidade do projeto, siga as orientações descritas abaixo.

1. Pré-requisitos do Ambiente

Java Development Kit (JDK): Versão 25 LTS (Eclipse Temurin, OpenJDK ou Amazon Corretto).
Maven Wrapper: Utilize sempre o executável ./mvnw (Linux/macOS) ou mvnw.cmd (Windows) embutido no projeto.
Git: Com suporte a quebra de linha LF.

2. Princípios de Segurança Invioláveis

Como este é um software de assinatura digital e custódia de credenciais criptográficas:

Nunca exponha credenciais: É estritamente proibido registrar, logar ou comitar PINs, senhas de arquivos A1, chaves privadas ou certificados de produção.
Testes isolados: Use fixtures mockadas ou certificados autoassinados temporários gerados dinamicamente nos testes.
Loopback estrito: O servidor CCSP escuta exclusivamente em 127.0.0.1:21325. Nunca altere o bind para interfaces externas.

3. Padrão de Commits

Adotamos a especificação Conventional Commits. Cada commit deve representar uma alteração coesa e atômica:

feat: Nova funcionalidade no agente, SDK ou UI.
fix: Correção de bug sem alteração de escopo.
docs: Alterações exclusivas na documentação.
test: Adição ou melhoria de suítes de testes.
refactor: Alterações de código que não mudam o comportamento funcional.
chore: Tarefas de manutenção de build, scripts ou dependências.
ci: Alterações no pipeline de CI/CD.

Exemplo: feat(core): add support for custom pkcs11 pin retry limit

4. Validação Pré-Commit / Pré-PR

Antes de submeter um Pull Request, certifique-se de que o build completo e todas as análises de qualidade passam localmente:

# Executa compilação, testes, checagem JaCoCo, SpotBugs e ArchUnit:
./mvnw clean verify

Critérios obrigatórios:

Todos os testes unitários e de integração devem passar com sucesso.
A cobertura mínima definida no jacoco:check de cada módulo deve ser mantida ou superada.
Nenhum novo apontamento de segurança ou erro do SpotBugs deve ser introduzido.

5. Fluxo de Pull Requests

Crie uma branch descritiva a partir de main (ex: feature/suporte-token-safenet ou fix/pades-timestamp-timeout).
Mantenha os commits organizados e pequenos.
Abra o Pull Request preenchendo o template oficial do repositório em .gitea/pull_request_template.md.
Garanta que o pipeline de CI do Gitea Actions finalize com status verde.

2.7 KiB Raw Blame History