Bem-vindo à Colaboração!
O que significa "Contribuir"?
Contribuir é como ajudar a melhorar um projeto em equipe. Imagine que vocês estão construindo uma casa juntos - cada pessoa faz uma parte (um pinta, outro faz o telhado, outro a elétrica) e no final fica pronto mais rápido e melhor!
Na programação, contribuir pode ser:
- Corrigir bugs: "Consertar coisas que não estão funcionando"
- Adicionar features: "Criar novas funcionalidades"
- Melhorar documentação: "Escrever explicações mais claras"
- Fazer testes: "Verificar se tudo funciona corretamente"
Fluxo de Contribuição na Cara Core
Seguimos um processo estruturado que garante qualidade e permite que múltiplas pessoas trabalhem no mesmo projeto sem conflitos:
- Issue/Task Assignment: Receber ou escolher uma tarefa
- Branch Creation: Criar uma branch específica para a tarefa
- Development: Desenvolver a solução localmente
- Testing: Testar e validar as mudanças
- Pull Request: Submeter para revisão
- Code Review: Revisão por pares
- Merge: Integração ao código principal
Git Flow da Cara Core
Explicação Simples
Git é como um "sistema de versões" do seu projeto. Imagine que você está escrevendo um livro:
- main/master: É o "livro oficial" publicado
- branches: São "rascunhos" onde você escreve capítulos novos
- commits: São "salvamentos" do seu progresso
- pull request: É pedir para alguém revisar seu capítulo antes de publicar
Comandos Práticos
1. Começar uma nova tarefa:
# Atualizar main local
git checkout main
git pull origin main
# Criar nova branch
git checkout -b feature/minha-tarefa
2. Trabalhar e salvar progresso:
# Adicionar mudanças
git add .
# Fazer commit
git commit -m "feat: adicionar nova funcionalidade"
# Enviar para GitHub
git push origin feature/minha-tarefa
Padrões de Commit
Usamos o padrão Conventional Commits para manter o histórico organizado:
✅ Commits Corretos
feat: adicionar login com Google
fix: corrigir bug no cadastro de usuários
docs: atualizar README com instruções
style: ajustar espaçamento no CSS
refactor: melhorar função de validação
test: adicionar testes para API de login
❌ Commits Ruins
mudanças
ajustes
fix
update
alterações no código
corrigido
melhorias
Tipos de Commit
- feat: Nova funcionalidade
- fix: Correção de bug
- docs: Documentação
- style: Formatação, espaçamento (sem mudança de lógica)
- refactor: Melhoria de código sem mudança de comportamento
- test: Adição ou correção de testes
- chore: Tarefas de manutenção (build, dependencies)
Processo de Pull Request
Passo a Passo Simples
- Termine sua tarefa na sua branch
- Teste tudo para garantir que funciona
- Envie para o GitHub (git push)
- Abra um Pull Request no site do GitHub
- Descreva o que você fez
- Aguarde a revisão de outro desenvolvedor
- Faça ajustes se necessário
- Celebre! Sua contribuição foi aceita
Template de PR
## Descrição
Breve descrição do que foi implementado/corrigido
## Tipo de mudança
- [ ] Bug fix
- [ ] Nova funcionalidade
- [ ] Breaking change
- [ ] Documentação
## Como testar
1. Execute o projeto localmente
2. Acesse a página X
3. Teste a funcionalidade Y
## Checklist
- [ ] Código testado localmente
- [ ] Testes automatizados passando
- [ ] Documentação atualizada
- [ ] Code review solicitado
Dicas para um PR Aprovado
- Seja específico: Explique claramente o que mudou
- Mantenha pequeno: PRs menores são mais fáceis de revisar
- Teste bem: Verifique se não quebrou nada
- Screenshots: Para mudanças visuais, inclua antes/depois
- Seja receptivo: Aceite feedback construtivo
Code Review
O que é Code Review?
É como ter um amigo revisando sua redação antes de entregar para o professor. Outro desenvolvedor lê seu código para:
- Verificar se está correto e funcionando
- Sugerir melhorias
- Garantir que segue os padrões da empresa
- Ensinar e aprender coisas novas
Não leve para o pessoal! Code review é sobre melhorar o código, não sobre julgar você como pessoa.
Como Dar/Receber Feedback
Dando Feedback:
- Seja construtivo e específico
- Explique o "porquê" das suas sugestões
- Reconheça coisas boas no código
- Sugira alternativas, não apenas critique
Recebendo Feedback:
- Seja aberto a sugestões
- Faça perguntas se não entender
- Agradeça o tempo do revisor
- Implemente as mudanças sugeridas
Boas Práticas de Desenvolvimento
- Nomes descritivos:
calculate_total_price() é melhor que calc()
- Funções pequenas: Máximo 20-30 linhas
- Comentários úteis: Explique o "porquê", não o "o quê"
- Consistência: Siga o padrão do projeto
- Nunca commite secrets: Senhas, API keys, tokens
- Valide inputs: Sempre verifique dados de usuário
- Use HTTPS: Especialmente em produção
- Logs seguros: Não logue informações sensíveis
- Teste antes de commitar: Verifique se não quebrou nada
- Escreva testes unitários: Para funções importantes
- Teste casos extremos: Valores nulos, limites
- Documente como testar: No README
- README atualizado: Como instalar e usar
- Docstrings: Documente funções públicas
- Changelog: Registre mudanças importantes
- Exemplos de uso: Code snippets práticos
Tipos de Contribuição
Existem várias formas de contribuir, independente do seu nível de experiência:
Iniciante
- Corrigir typos na documentação
- Melhorar mensagens de erro
- Adicionar exemplos no README
- Testar e reportar bugs
- Traduzir conteúdo
Intermediário
- Implementar pequenas features
- Corrigir bugs simples
- Escrever testes unitários
- Melhorar performance
- Refatorar código legado
Avançado
- Arquitetar novas funcionalidades
- Otimizar performance crítica
- Implementar integrações complexas
- Revisar PRs de outros
- Mentoriar estagiários
Ferramentas para Contribuição
Checklist de Setup
- ✅ Git configurado com seu nome/email
- ✅ SSH key configurada no GitHub
- ✅ VS Code com extensões necessárias
- ✅ Python 3.11+ instalado
- ✅ Acesso aos repositórios da empresa
Comandos Úteis
# Ver status do projeto
git status
# Ver histórico de commits
git log --oneline
# Trocar de branch
git checkout nome-da-branch
# Ver diferenças
git diff
# Desfazer mudanças locais
git checkout -- arquivo.py
Pronto para Contribuir?
Agora você tem todo conhecimento necessário para começar a contribuir!
Sua Primeira Contribuição
Recomendamos começar com algo pequeno: corrigir um typo, melhorar um comentário ou adicionar um exemplo. O importante é praticar o fluxo!