Pular para conteúdo

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

  1. Fork o repositório
  2. Crie uma branch para sua feature/contribution: 
    git checkout -b feature/minha-feature
  3. Faça suas alterações seguindo os padrões do projeto
  4. Teste suas alterações
  5. Commit suas alterações seguindo as convenções: 
    git commit -m "feat: adiciona nova funcionalidade X"
  6. Push para sua branch: 
    git push origin feature/minha-feature
  7. 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

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

Veja Como Rodar Localmente para mais informações.

Recursos Adicionais