Onboarding de contribuidores
Novos contribuidores precisam de três coisas: um caminho (CONTRIBUTING.md), um mapa (labels) e um primeiro passo (good first issues). Construa tudo isso a partir dos comandos reais do projeto.
Quando usar
- "Escreva um CONTRIBUTING.md" / "como consigo contribuidores?"
- Criar ou limpar labels no GitHub
- Escrever boas primeiras issues, ou preparar para Hacktoberfest ou um lançamento
Quando não usar
- Documentos de governança para fundações (GOVERNANCE.md, charters): fora do escopo.
- Texto de código de conduta: adote o Contributor Covenant como está; não o reescreva.
Fluxo de trabalho
1. CONTRIBUTING.md
- Encontre os comandos reais: setup (
pip install -e ".[dev]",npm ci,composer install), testes, lint/format, build, docs. Leia os workflows de CI; eles são a fonte da verdade. - Copie o template e preencha cada espaço reservado. Execute cada comando que você documentar, ou diga claramente quais não conseguiu executar.
- Mantenha escaneável: formas de contribuir (por tempo necessário), setup, testes, estilo, convenção de commits, processo de PR, onde perguntar. Link para CODE_OF_CONDUCT.md e SECURITY.md.
- Adicione de 5 a 10 tarefas concretas para iniciantes sob "Boas primeiras issues" ou link para a label.
2. Labels
scripts/ é relativo ao diretório desta skill. O script nunca chama o GitHub diretamente.
python3 scripts/labels.py generate > labels.json # conjunto padrão
python3 scripts/labels.py generate --area cli --area docs --prefixed > labels.json
python3 scripts/labels.py validate labels.json # exit 1 se houver problemas
python3 scripts/labels.py commands labels.json --repo OWNER/NOME > apply-labels.sh
Mostre ao usuário o apply-labels.sh e peça permissão antes de executá-lo: ele cria ou atualiza
labels no GitHub (gh label create ... --force). Ele nunca exclui labels. Se o usuário quiser
remover labels antigas, liste-as com gh label list e confirme cada exclusão.
Mantenha os nomes good first issue e help wanted do GitHub inalterados: o GitHub e
sites terceiros os usam para exibir tarefas para iniciantes.
3. Boas primeiras issues
Reescreva issues candidatas seguindo o guia. Cada uma precisa de: contexto, os arquivos exatos a modificar, critérios de aceitação, como testar e uma oferta de ajuda. Peça permissão antes de editar ou rotular issues no GitHub; ofereça o texto como rascunho primeiro.
Saída
- CONTRIBUTING.md (novo ou atualizado) e uma lista de comandos verificados vs. não verificados.
labels.jsoneapply-labels.sh(não executados a menos que o usuário aprove).- Boas primeiras issues redigidas em Markdown, prontas para colar ou para criar com
gh issue create --title ... --body-file ... --label "good first issue"após aprovação.
Conjunto padrão de labels
| Grupo | Labels |
|---|---|
| tipo | bug, enhancement, documentation, question, performance, refactor |
| contribuidor | good first issue, help wanted |
| status | needs-triage, needs-repro, needs-info, confirmed, in-progress, blocked, stale |
| prioridade | priority: critical, priority: high, priority: low |
| resolução | duplicate, invalid, wontfix |
| dependências | dependencies, security, breaking-change |
--prefixed altera para nomes no estilo type: bug, status: needs triage. O GitHub limita
nomes de labels a 50 caracteres e descrições a 100; validate verifica ambos, além de
cores hexadecimais de 6 dígitos e duplicatas sem distinção entre maiúsculas e minúsculas.