Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
273 lines (198 loc) · 6.5 KB

CONTRIBUTING.md

File metadata and controls

273 lines (198 loc) · 6.5 KB

Guia de Contribuição - ProcessarLoteNFe

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

🚀 Como Contribuir

1. Reportando Bugs

Antes de criar um issue para um bug, verifique se:

  • O bug não foi já reportado
  • Você está usando a versão mais recente
  • O bug é reproduzível

Template para reportar bugs:

**Descrição do Bug**
Uma descrição clara e concisa do que é o bug.

**Para Reproduzir**
1. Vá para '...'
2. Clique em '...'
3. Role até '...'
4. Veja o erro

**Comportamento Esperado**
Uma descrição clara do que deveria acontecer.

**Screenshots**
Se aplicável, adicione screenshots para ajudar a explicar o problema.

**Ambiente:**
- OS: [ex: Windows 10, macOS 12.0, Ubuntu 20.04]
- PowerShell: [ex: 7.5.2]
- Versão do Script: [ex: 2.2.0]

**Informações Adicionais**
Qualquer outra informação sobre o problema aqui.

2. Sugerindo Melhorias

Template para sugestões:

**Sua sugestão está relacionada a um problema?**
Uma descrição clara e concisa do problema.

**Descreva a solução que você gostaria**
Uma descrição clara e concisa do que você quer que aconteça.

**Descreva alternativas que você considerou**
Uma descrição clara e concisa de quaisquer soluções ou recursos alternativos que você considerou.

**Contexto adicional**
Adicione qualquer outro contexto ou screenshots sobre a sugestão aqui.

3. Contribuindo com Código

Configurando o Ambiente de Desenvolvimento

  1. Fork o repositório

    git clone https://github.com/seu-usuario/ProcessarLoteNFe.git
cd ProcessarLoteNFe

  2. Crie uma branch para sua feature

    git checkout -b feature/nova-funcionalidade

  3. Faça suas alterações

    • Siga as convenções de código
    • Adicione testes se aplicável
    • Atualize a documentação

  4. Commit suas mudanças

    git commit -m "feat: adiciona nova funcionalidade"

  5. Push para a branch

    git push origin feature/nova-funcionalidade

  6. Abra um Pull Request

Convenções de Commit

Use o formato Conventional Commits:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Tipos:

  • feat: Nova funcionalidade
  • fix: Correção de bug
  • docs: Documentação
  • style: Formatação, ponto e vírgula, etc.
  • refactor: Refatoração de código
  • test: Adicionando testes
  • chore: Tarefas de manutenção

Exemplos:

git commit -m "feat: adiciona suporte a processamento paralelo"
git commit -m "fix: corrige regex para códigos com hífen"
git commit -m "docs: atualiza README com novos exemplos"

Padrões de Código

PowerShell:

  • Use PascalCase para variáveis globais
  • Use camelCase para variáveis locais
  • Use Verb-Noun para nomes de funções
  • Comente blocos complexos
  • Use aspas duplas para strings

Exemplo:

# ✅ Bom
$pastaOrigem = "/caminho/para/pasta"
$arquivosProcessados = 0

function Processar-ArquivoXML {
    param([string]$caminhoArquivo)
    # Lógica aqui
}

# ❌ Evitar
$pasta_origem = "/caminho/para/pasta"
$arquivos_processados = 0

function processar_arquivo_xml {
    param([string]$caminho_arquivo)
    # Lógica aqui
}

4. Documentação

Atualizando Documentação

  • Mantenha o README.md atualizado
  • Documente novas funcionalidades
  • Atualize exemplos quando necessário
  • Mantenha o CHANGELOG.md atualizado

Estrutura de Documentação

docs/
├── technical-specs.md     # Especificações técnicas
├── examples/              # Exemplos de uso
│   └── example-usage.md
└── api/                   # Documentação da API (futuro)

5. Testes

Executando Testes

# Teste básico
pwsh -NoProfile -Command "& './ProcessarLoteNFe.ps1'"

# Teste com arquivos de exemplo
cp sample/test.xml /tmp/test/
pwsh -NoProfile -Command "& './ProcessarLoteNFe.ps1'"

Criando Testes

  1. Crie arquivos XML de teste em tests/
  2. Documente casos de teste esperados
  3. Execute testes antes de submeter PR

6. Pull Request

Checklist para PR

  • Código segue as convenções
  • Documentação foi atualizada
  • Testes foram adicionados/atualizados
  • CHANGELOG.md foi atualizado
  • Código foi testado localmente

Template para PR

## Descrição
Breve descrição das mudanças.

## Tipo de Mudança
- [ ] Bug fix (mudança que corrige um problema)
- [ ] Nova feature (mudança que adiciona funcionalidade)
- [ ] Breaking change (correção ou feature que faria com que funcionalidade existente não funcionasse como esperado)
- [ ] Documentação

## Como Testar
1. Clone o repositório
2. Configure o ambiente
3. Execute os testes
4. Verifique se tudo funciona

## Screenshots (se aplicável)
Adicione screenshots para ajudar a explicar suas mudanças.

## Checklist
- [ ] Meu código segue as diretrizes de estilo deste projeto
- [ ] Eu fiz uma auto-revisão do meu próprio código
- [ ] Eu comentei meu código, particularmente em áreas difíceis de entender
- [ ] Eu fiz as mudanças correspondentes na documentação
- [ ] Minhas mudanças não geram novos warnings
- [ ] Eu adicionei testes que provam que minha correção é eficaz ou que minha feature funciona
- [ ] Testes novos e existentes passam localmente com minhas mudanças
- [ ] Quaisquer mudanças dependentes foram mergeadas e publicadas em módulos downstream

📋 Diretrizes Gerais

Comunicação

  • Seja respeitoso e construtivo
  • Use português ou inglês
  • Forneça contexto suficiente
  • Responda a feedback de forma profissional

Qualidade

  • Teste suas mudanças
  • Mantenha o código limpo e legível
  • Documente funcionalidades complexas
  • Siga as convenções existentes

Responsabilidades

  • Mantenha-se atualizado com a base de código
  • Responda a issues e PRs em tempo hábil
  • Forneça feedback construtivo
  • Ajude outros contribuidores

🏆 Reconhecimento

Contribuidores serão reconhecidos no README.md e em releases do projeto.

Níveis de Contribuição

  • Contribuidor: 1-5 PRs aceitos
  • Colaborador: 5+ PRs aceitos
  • Mantenedor: Contribuições significativas e consistentes

📞 Suporte

Se você tiver dúvidas sobre como contribuir:

  • Abra uma issue com a tag question
  • Entre em contato via email
  • Participe das discussões em issues existentes

Obrigado por contribuir com o ProcessarLoteNFe! 🚀