488 lines
9.0 KiB
Markdown
488 lines
9.0 KiB
Markdown
# 🎹 Guia de Contribuição - Piano Training Platform
|
|
|
|
Obrigado por contribuir! Este guia ajudará você a começar.
|
|
|
|
## 📋 Índice
|
|
|
|
- [Código de Conduta](#código-de-conduta)
|
|
- [Como Contribuir](#como-contribuir)
|
|
- [Configuração do Ambiente](#configuração-do-ambiente)
|
|
- [Padrões de Código](#padrões-de-código)
|
|
- [Regras de Review](#regras-de-review)
|
|
- [Processo de Pull Request](#processo-de-pull-request)
|
|
- [Testes](#testes)
|
|
- [Documentação](#documentação)
|
|
|
|
---
|
|
|
|
## 📜 Código de Conduta
|
|
|
|
- Seja respeitoso e inclusivo
|
|
- Forneça feedback construtivo
|
|
- Aceite críticas com profissionalismo
|
|
- Foque no que é melhor para a comunidade
|
|
|
|
---
|
|
|
|
## 🤝 Como Contribuir
|
|
|
|
### Formas de Contribuir
|
|
|
|
1. **Reportar Bugs**: Abra uma issue com detalhes
|
|
2. **Sugerir Features**: Use o template de feature request
|
|
3. **Melhorar Documentação**: PRs de documentação são sempre bem-vindos
|
|
4. **Corrigir Bugs**: Veja issues marcadas com `good first issue`
|
|
5. **Implementar Features**: Escolha issues do roadmap
|
|
|
|
### Antes de Começar
|
|
|
|
1. Verifique se já existe uma issue relacionada
|
|
2. Comente na issue que você pretende trabalhar nela
|
|
3. Aguarde aprovação do mantenedor antes de começar código grande
|
|
4. Para pequenas correções, pode ir direto ao PR
|
|
|
|
---
|
|
|
|
## 🛠️ Configuração do Ambiente
|
|
|
|
### Pré-requisitos
|
|
|
|
```bash
|
|
# Node.js >= 18
|
|
node --version
|
|
|
|
# Python >= 3.10
|
|
python --version
|
|
|
|
# Git
|
|
git --version
|
|
```
|
|
|
|
### Instalação
|
|
|
|
```bash
|
|
# 1. Fork o repositório no GitHub
|
|
|
|
# 2. Clone seu fork
|
|
git clone https://github.com/SEU-USERNAME/skills.git
|
|
cd skills
|
|
|
|
# 3. Adicione o upstream
|
|
git remote add upstream https://github.com/criptolandiatv/skills.git
|
|
|
|
# 4. Instale dependências do frontend
|
|
npm install
|
|
|
|
# 5. Instale dependências do backend
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
# ou
|
|
poetry install
|
|
|
|
# 6. Configure variáveis de ambiente
|
|
cp .env.example .env
|
|
# Edite .env com suas credenciais
|
|
|
|
# 7. Execute os testes
|
|
npm test
|
|
cd backend && pytest
|
|
```
|
|
|
|
### Desenvolvimento
|
|
|
|
```bash
|
|
# Terminal 1: Frontend
|
|
npm run dev
|
|
|
|
# Terminal 2: Backend
|
|
cd backend
|
|
python start_server.py
|
|
|
|
# Terminal 3: Redis (se necessário)
|
|
redis-server
|
|
|
|
# Terminal 4: Celery (se necessário)
|
|
cd backend
|
|
celery -A app.celery worker --loglevel=info
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 Padrões de Código
|
|
|
|
### Naming Conventions
|
|
|
|
**Componentes React**:
|
|
```typescript
|
|
// PascalCase para componentes
|
|
export const PianoKeyboard: React.FC<Props> = ({ ... }) => { ... };
|
|
|
|
// camelCase para funções e variáveis
|
|
const handleNotePress = (note: string) => { ... };
|
|
|
|
// SCREAMING_SNAKE_CASE para constantes
|
|
const MAX_VELOCITY = 127;
|
|
```
|
|
|
|
**Arquivos**:
|
|
```
|
|
PianoKeyboard.tsx # Componentes
|
|
useGamification.ts # Hooks
|
|
piano-utils.ts # Utilities
|
|
PianoKeyboard.test.tsx # Testes
|
|
PianoKeyboard.css # Estilos
|
|
```
|
|
|
|
### Estrutura de Componentes
|
|
|
|
```typescript
|
|
import React, { useState, useEffect } from 'react';
|
|
import './Component.css';
|
|
|
|
// 1. Interfaces/Types
|
|
interface Props {
|
|
prop1: string;
|
|
prop2?: number;
|
|
}
|
|
|
|
// 2. Componente
|
|
export const Component: React.FC<Props> = ({ prop1, prop2 = 0 }) => {
|
|
// 2.1. State
|
|
const [state, setState] = useState<Type>(initialValue);
|
|
|
|
// 2.2. Effects
|
|
useEffect(() => {
|
|
// ...
|
|
return () => {
|
|
// Cleanup
|
|
};
|
|
}, [dependencies]);
|
|
|
|
// 2.3. Handlers
|
|
const handleEvent = () => {
|
|
// ...
|
|
};
|
|
|
|
// 2.4. Render
|
|
return (
|
|
<div className="component">
|
|
{/* JSX */}
|
|
</div>
|
|
);
|
|
};
|
|
```
|
|
|
|
### Commits (Conventional Commits)
|
|
|
|
```bash
|
|
feat: adiciona componente de teclado virtual
|
|
fix: corrige latência no MIDI input
|
|
docs: atualiza README com instruções de setup
|
|
refactor: simplifica lógica de gamificação
|
|
test: adiciona testes para ScoreFollower
|
|
perf: otimiza renderização de partituras
|
|
style: formata código com Prettier
|
|
chore: atualiza dependências
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 Regras de Review
|
|
|
|
### ⚠️ Bloqueantes (Impedem Merge)
|
|
|
|
#### Componentes
|
|
- [ ] Componentes têm PropTypes ou TypeScript types
|
|
- [ ] Sem lógica de negócio dentro de componentes UI
|
|
- [ ] Componentes são testáveis
|
|
|
|
#### Áudio/MIDI
|
|
- [ ] Código de áudio tem try-catch
|
|
- [ ] Cleanup de recursos implementado (removeEventListener)
|
|
- [ ] Latência documentada (alvo: < 50ms)
|
|
|
|
#### Estado
|
|
- [ ] Estado gerenciado de forma imutável
|
|
- [ ] Sem lógica complexa em reducers
|
|
|
|
#### Testes
|
|
- [ ] Nova funcionalidade tem ≥ 1 teste
|
|
- [ ] Coverage mínimo de 70% em arquivos novos
|
|
|
|
#### API/Backend
|
|
- [ ] Chamadas API têm timeout
|
|
- [ ] Retry logic implementado
|
|
- [ ] Validação de dados da API
|
|
- [ ] Sem secrets expostos
|
|
|
|
### 🟡 Fortemente Recomendado
|
|
|
|
- Componentes < 250 linhas
|
|
- Acessibilidade (WCAG 2.1)
|
|
- Performance otimizada
|
|
- Documentação atualizada
|
|
|
|
### 📝 Verificação Automática
|
|
|
|
```bash
|
|
# Antes de fazer commit:
|
|
npm run lint # ESLint
|
|
npm run format:check # Prettier
|
|
npm test # Testes
|
|
npm run type-check # TypeScript
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Processo de Pull Request
|
|
|
|
### 1. Crie uma Branch
|
|
|
|
```bash
|
|
git checkout -b feature/nome-da-feature
|
|
# ou
|
|
git checkout -b fix/nome-do-bug
|
|
```
|
|
|
|
### 2. Faça suas Mudanças
|
|
|
|
```bash
|
|
# Commit frequentemente
|
|
git add .
|
|
git commit -m "feat: implementa funcionalidade X"
|
|
```
|
|
|
|
### 3. Mantenha Atualizado
|
|
|
|
```bash
|
|
# Periodicamente, sincronize com upstream
|
|
git fetch upstream
|
|
git rebase upstream/main
|
|
```
|
|
|
|
### 4. Execute Verificações
|
|
|
|
```bash
|
|
# Lint e format
|
|
npm run lint
|
|
npm run format
|
|
|
|
# Testes
|
|
npm test
|
|
|
|
# Build
|
|
npm run build
|
|
|
|
# Backend
|
|
cd backend
|
|
flake8 app/
|
|
black app/
|
|
pytest
|
|
```
|
|
|
|
### 5. Push e Abra PR
|
|
|
|
```bash
|
|
git push origin feature/nome-da-feature
|
|
```
|
|
|
|
No GitHub:
|
|
1. Abra Pull Request
|
|
2. Preencha o template completamente
|
|
3. Aguarde CI passar
|
|
4. Responda a feedbacks de reviewers
|
|
|
|
### 6. Após Aprovação
|
|
|
|
```bash
|
|
# Squash commits se necessário
|
|
git rebase -i HEAD~N
|
|
|
|
# Force push (cuidado!)
|
|
git push --force-with-lease
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testes
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
# Rodar todos os testes
|
|
npm test
|
|
|
|
# Rodar com coverage
|
|
npm test -- --coverage
|
|
|
|
# Rodar em watch mode
|
|
npm test -- --watch
|
|
|
|
# Rodar testes específicos
|
|
npm test -- MidiPlayer
|
|
```
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Rodar todos os testes
|
|
pytest
|
|
|
|
# Com coverage
|
|
pytest --cov=app --cov-report=html
|
|
|
|
# Testes específicos
|
|
pytest tests/test_score_following.py
|
|
|
|
# Com verbosidade
|
|
pytest -v
|
|
```
|
|
|
|
### Estrutura de Teste
|
|
|
|
```typescript
|
|
// Component.test.tsx
|
|
import { render, screen, fireEvent } from '@testing-library/react';
|
|
import { Component } from './Component';
|
|
|
|
describe('Component', () => {
|
|
it('should render correctly', () => {
|
|
render(<Component prop="value" />);
|
|
expect(screen.getByText('Expected Text')).toBeInTheDocument();
|
|
});
|
|
|
|
it('should handle events', () => {
|
|
const handleClick = jest.fn();
|
|
render(<Component onClick={handleClick} />);
|
|
|
|
fireEvent.click(screen.getByRole('button'));
|
|
expect(handleClick).toHaveBeenCalledTimes(1);
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Documentação
|
|
|
|
### JSDoc
|
|
|
|
```typescript
|
|
/**
|
|
* Converte nota MIDI (0-127) para frequência em Hz
|
|
*
|
|
* @param midiNote - Número da nota MIDI (0-127)
|
|
* @returns Frequência em Hz
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* midiToFrequency(69); // 440 (A4)
|
|
* ```
|
|
*/
|
|
export const midiToFrequency = (midiNote: number): number => {
|
|
return 440 * Math.pow(2, (midiNote - 69) / 12);
|
|
};
|
|
```
|
|
|
|
### README
|
|
|
|
Ao adicionar nova feature, atualize:
|
|
- `README.md` - Overview geral
|
|
- `FEATURE_X_README.md` - Documentação específica
|
|
- `MVP_TESTING_GUIDE.md` - Se afeta testes
|
|
|
|
---
|
|
|
|
## 🎯 Áreas Específicas
|
|
|
|
### Componentes de Áudio/MIDI
|
|
|
|
```typescript
|
|
// Sempre implemente cleanup
|
|
useEffect(() => {
|
|
const audioContext = new AudioContext();
|
|
|
|
return () => {
|
|
audioContext.close(); // ✅ Cleanup
|
|
};
|
|
}, []);
|
|
```
|
|
|
|
### Teclado Virtual
|
|
|
|
- Suporte touch + mouse
|
|
- Resposta < 100ms
|
|
- Feedback visual imediato
|
|
- Múltiplas teclas (acordes)
|
|
|
|
### Sistema de Avaliação
|
|
|
|
- Feedback construtivo
|
|
- Tolerar desvios humanos (±50ms)
|
|
- Progress tracking
|
|
- Métricas documentadas
|
|
|
|
---
|
|
|
|
## 🐛 Reportando Bugs
|
|
|
|
Use o template de issue com:
|
|
|
|
1. **Descrição**: O que aconteceu
|
|
2. **Esperado**: O que deveria acontecer
|
|
3. **Passos para Reproduzir**: 1, 2, 3...
|
|
4. **Ambiente**: OS, Browser, versões
|
|
5. **Screenshots**: Se aplicável
|
|
6. **Logs**: Console errors
|
|
|
|
---
|
|
|
|
## 💡 Sugerindo Features
|
|
|
|
1. Verifique se já não existe issue similar
|
|
2. Descreva o problema que resolve
|
|
3. Proponha solução
|
|
4. Considere alternativas
|
|
5. Adicione mockups/wireframes se possível
|
|
|
|
---
|
|
|
|
## 🏆 Boas Práticas
|
|
|
|
### DOs ✅
|
|
|
|
- Escreva testes antes de implementar (TDD)
|
|
- Faça commits pequenos e frequentes
|
|
- Mantenha PRs focados (1 feature por PR)
|
|
- Documente decisões arquiteturais importantes
|
|
- Peça ajuda quando travar
|
|
|
|
### DON'Ts ❌
|
|
|
|
- Não commite código comentado
|
|
- Não deixe console.log em produção
|
|
- Não faça PRs gigantes (> 500 linhas)
|
|
- Não ignore warnings do linter
|
|
- Não pule testes
|
|
|
|
---
|
|
|
|
## 📞 Contato
|
|
|
|
- **Issues**: https://github.com/criptolandiatv/skills/issues
|
|
- **Discussions**: https://github.com/criptolandiatv/skills/discussions
|
|
- **Email**: [seu-email]
|
|
|
|
---
|
|
|
|
## 🙏 Reconhecimentos
|
|
|
|
Obrigado a todos os contribuidores que tornam este projeto possível!
|
|
|
|
---
|
|
|
|
**Última atualização**: 2025-10-25
|
|
**Versão**: 1.0.0
|