Guia de Contribuição - ecosif-masterdata

Boas-vindas!

Obrigado por considerar contribuir com o projeto ecosif-masterdata! Este documento fornece diretrizes para contribuições.

Como Contribuir

1. Reportar Problemas (Issues)

Antes de criar uma issue: - Verifique se o problema já foi reportado - Certifique-se de que está usando a versão mais recente - Colete informações relevantes (logs, versão, ambiente)

Ao criar uma issue, inclua: - Descrição clara do problema - Passos para reproduzir - Comportamento esperado vs. atual - Logs relevantes (sem informações sensíveis) - Ambiente (OS, Java version, etc.)

2. Sugerir Melhorias

Para sugerir melhorias: - Abra uma issue com label "enhancement" - Descreva o problema que a melhoria resolveria - Explique como a melhoria funcionaria - Inclua exemplos de uso se aplicável

3. Contribuir com Código

Processo

Fork o repositório
Crie uma branch para sua feature/contribution: bash git checkout -b feature/minha-feature
Faça suas alterações seguindo os padrões do projeto
Teste suas alterações
Commit suas alterações seguindo as convenções: bash git commit -m "feat: adiciona nova funcionalidade X"
Push para sua branch: bash git push origin feature/minha-feature
Abra um Pull Request

Padrões de Código

Estrutura de Packages

io.ecosif.masterdata
├── company/
│   ├── controller/      # Controllers REST
│   ├── service/         # Services de negócio
│   ├── repository/      # Repositories JPA
│   ├── dto/             # DTOs
│   └── integration/     # Integrações externas
├── config/              # Configurações
├── security/            # Segurança
└── user/                # Usuários

Anotações Spring

Use @Service para serviços de negócio
Use @Repository para repositórios
Use @RestController para controllers REST

Validação

Valide DTOs de entrada usando Bean Validation
Valide lógica de negócio nos Services
Retorne códigos HTTP apropriados

Tratamento de Exceções

Use exceções customizadas quando apropriado
Sempre trate exceções no GlobalExceptionHandler
Não exponha detalhes internos em mensagens de erro

Logs

Use @Slf4j do Lombok para logging
Use níveis apropriados (ERROR, WARN, INFO, DEBUG)
Não logue informações sensíveis

Documentação

Documente endpoints com Swagger (@Operation, @ApiResponses)
Documente métodos públicos com JavaDoc

Convenções de Commit

Seguimos o padrão Conventional Commits:

<tipo>(<escopo>): <descrição curta>

[corpo opcional]

[rodapé opcional]

Tipos: - feat: Nova funcionalidade - fix: Correção de bug - docs: Documentação - refactor: Refatoração - test: Testes - chore: Tarefas de manutenção

Exemplos:

feat(company): adiciona validação de CNPJ
fix(branch): corrige criação de CompanyOptions
docs(api): atualiza documentação do endpoint /company

Ambiente de Desenvolvimento

Pré-requisitos

Java 17+
Maven 3.6+
PostgreSQL 13+
Docker (opcional)

Configuração Inicial

Clone o repositório
Configure as variáveis de ambiente
Execute a aplicação

Veja Como Rodar Localmente para mais informações.