Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
200 lines (141 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

200 lines (141 loc) · 4.87 KB

Contribuindo para Algoritmos e Programação para Física

Agradecemos interesse em contribuir! Este projeto é voltado para educação e toda contribuição é bem-vinda.

📋 Diretrizes de Contribuição

Tipos de Contribuição

  • Correções de erros: Typos, erros matemáticos, bugs no código
  • Melhorias: Explicações mais claras, novos exemplos, visualizações
  • Novas funcionalidades: Novos capítulos, exercícios, notebooks
  • Documentação: Melhorias na clareza e cobertura
  • Tradução: Adaptar para outras línguas

Como Contribuir

  1. Fork o repositório
  2. Clone seu fork: git clone https://github.com/seu-usuario/algoritmos-programacao-fisica.git
  3. Crie uma branch: git checkout -b feature/sua-contribuicao
  4. Faça suas mudanças (veja detalhes abaixo)
  5. Commit: git commit -m "Descrição clara da mudança"
  6. Push: git push origin feature/sua-contribuicao
  7. Abra um Pull Request com descrição detalhada

Diretrizes de Código

Para Português Estruturado (VisualG)

// ✓ BOM: Código claro e bem comentado
funcao CalcularEnergia(massa: real, velocidade: real): real
var
   energia: real
inicio
   // Energia cinética = (1/2) * m * v²
   energia <- 0.5 * massa * velocidade * velocidade
   retorne energia
fimfuncao

// ✗ RUIM: Falta clareza
f <- 0.5 * m * v * v

Para Python

# ✓ BOM: Segue PEP 8, bem documentado
def calcular_energia_cinetica(massa: float, velocidade: float) -> float:
    """
    Calcula a energia cinética de um objeto.
    
    Args:
        massa: massa em kg
        velocidade: velocidade em m/s
    
    Returns:
        float: energia cinética em joules
    
    Examples:
        >>> calcular_energia_cinetica(5.0, 10.0)
        250.0
    """
    return 0.5 * massa * velocidade ** 2

# ✗ RUIM: Falta documentação
def ec(m, v):
    return 0.5 * m * v ** 2

Diretrizes para Markdown

  • Use # para títulos (máximo 3 níveis na apostila)
  • Indente código com 4 espaços ou ```
  • Use negrito para conceitos importantes
  • Use $...$ para fórmulas inline e $$...$$ para display em MathJax
  • Mantenha linhas com menos de 100 caracteres

Exemplo:

### Conceito Importante

Use a fórmula $E = mc^2$ para calcular energia. Para cálculos mais complexos:

$$\int_0^{2\pi} \sin(x) dx = 2$$

**Nota importante:** Sempre valide seus cálculos!

Diretrizes para Jupyter Notebooks

  1. Estrutura:

    • Título e descrição no início
    • Imports no topo
    • Markdown explicativo antes do código
    • Uma ideia por célula

  2. Comentários:

    • Código bem comentado
    • Explicações em Markdown
    • Resultados interpretados

  3. Execução:

    • Teste o notebook antes de submeter
    • Todos os outputs devem estar presentes
    • Limpe Out[*] numbers se editado manualmente

Diretrizes para Fórmulas Matemáticas

✓ BOM:
Energia cinética: $E_c = \frac{1}{2}mv^2$

Altura máxima:
$$H = \frac{v_0^2 \sin^2(\theta)}{2g}$$

✗ RUIM:
Ec = (1/2) * m * v^2
H = (v0^2 * sin²(θ)) / (2*g)

📝 Padrão de Commit

tipo(escopo): descrição breve

Descrição detalhada se necessário (máx 72 caracteres por linha)

Fixes #123 (se aplicável)

Tipos de Commit

  • docs: Documentação
  • feat: Nova funcionalidade
  • fix: Correção de bug
  • refactor: Refatoração de código
  • style: Formatação
  • test: Testes
  • chore: Tarefas administrativas

Exemplos

feat(cap-8): adicionar método de Newton-Raphson

docs(readme): esclarecer instalação de dependências

fix(notebook-02): corrigir erro na fórmula de produto escalar

refactor(apostila): melhorar estrutura do capítulo 5

🔍 Revisão de Pull Request

O que analisamos

  • ✅ Clareza e correção do conteúdo
  • ✅ Conformidade com diretrizes
  • ✅ Fórmulas matemáticas corretas
  • ✅ Código executável e testado
  • ✅ Documentação apropriada
  • ✅ Sem mudanças desnecessárias

Feedback

  • Seremos construtivos e educados
  • Explicitaremos o raciocínio
  • Sugeriremos melhorias quando necessário
  • Respeitaremos seu tempo

❓ Perguntas Frequentes

P: Posso traduzir para outro idioma? R: Sim! Crie um diretório separado (ex: /en/, /es/)

P: Posso adicionar um novo capítulo? R: Sim, mas coordene conosco primeiro via issue

P: E se descobrir um erro? R: Abra uma issue descrevendo claramente o erro com exemplos

P: Quanto tempo leva para review? R: Tentamos responder em até 1 semana

📞 Dúvidas?

  • Issues: Para bugs, erros ou perguntas
  • Discussions: Para ideias e discussões
  • Email: Acesse os detalhes do projeto

🙏 Agradecimentos

Toda contribuição é valiosa e apreciada! Você será creditado apropriadamente.

Obrigado por melhorar este projeto! 🌟

Lembre-se: Este é um projeto educacional. Priorize clareza e qualidade pedagógica.