Template CONTRIBUTING

CONTRIBUTING.md: o manual do contribuidor num projeto open source

Se o README.md é o pitch para o visitante, o CONTRIBUTING.md é o manual do contribuidor. É o documento que transforma um desconhecido interessado em co-autor produtivo, e a sua ausência é a razão mais comum pela qual projetos saudáveis falham em escalar além do mantenedor original. O próprio GitHub auto-descobre o arquivo: quando o usuário abre uma nova issue ou pull request, a plataforma automaticamente renderiza um link "Please read our contributing guidelines" se o arquivo existe, elevando o compliance drasticamente sem nenhum trabalho custom.

As seções clássicas estão bem estabelecidas. Um CONTRIBUTING.md canônico cobre: link para o Code of Conduct, como reportar bugs (idealmente apontando para um .github/ISSUE_TEMPLATE), como sugerir features, setup de desenvolvimento (clone, install, env), padrões de código (style guide, formatter, linter), workflow Git (convenção de branch, estilo de commit — Conventional Commits é o padrão de fato), requisitos de teste, o processo de pull request, o processo de revisão e finalmente os canais de comunicação (Discord, Slack, mailing list).

Code of Conduct, CLA e DCO

Três artefatos legais e culturais frequentemente referenciados a partir do CONTRIBUTING. O Code of Conduct vive em arquivo próprio (CODE_OF_CONDUCT.md) — o padrão dominante é o Contributor Covenant de Coraline Ada Ehmke, adotado por Linux, Kubernetes, Node.js e milhares de outros. Um CLA (Contributor License Agreement) é exigido por alguns projetos com respaldo corporativo (Google, Facebook, a Apache Foundation) e cede ou licencia o copyright da contribuição para a entidade. Uma alternativa mais leve é o DCO (Developer Certificate of Origin), usado pelo kernel Linux: contribuidores adicionam Signed-off-by: em cada commit e atestam que têm o direito de submeter a mudança.

Onboarding gradual e experiência do contribuidor

Projetos bem-sucedidos desenham uma escada de contribuição: visitantes de primeira viagem encontram labels good first issue e help wanted, depois graduam para issues regulares, depois para triagem e revisão. A iniciativa First Timers Only formalizou isso — labels e linguagem acolhedora desenhados para iniciantes absolutos. Programas de mentoria amplificam o funil: Outreachy, Google Summer of Code, Rails Girls Summer of Code pagam pessoas para fazer seus primeiros patches. Reconhecimento importa também — a spec All Contributors usa atribuição por emoji (code, docs, design, review) para que trabalho não-código apareça no README.

Tooling: linters, hooks, CI e financiamento

Um CONTRIBUTING moderno é meio contrato social, meio referência de tooling. Hooks de pre-commit via husky + lint-staged (Node) ou pre-commit (Python) impõem formatação localmente. CI roda a mesma suíte — GitHub Actions, CircleCI e o veterano Travis CI são as escolhas usuais. Estilo é imposto por Prettier + ESLint em JS, Black + ruff em Python, gofmt em Go. Sites de documentação usam Docusaurus, ReadTheDocs ou VitePress. Rituais culturais — Hacktoberfest em outubro — disparam ondas sazonais de contribuição. E a seção de financiamento, com links de GitHub Sponsors, Open Collective ou Patreon, deixa a sustentabilidade explícita.

Perguntas frequentes

CONTRIBUTING.md é obrigatório? Tecnicamente não — seu repo funciona sem ele. Na prática, qualquer projeto que quer contribuições externas precisa de um; a ausência sinaliza "ainda não estou pronto para colaboradores" e a maioria dos contribuidores experientes vai seguir em frente.

Que tamanho ele deve ter? Uma a três telas. Longo o bastante para cobrir setup, estilo e processo de PR; curto o bastante para que alguém realmente leia antes de abrir um PR. Encaminhe o detalhe para arquivos linkados (CODE_OF_CONDUCT, dev docs, ADRs).

Deve ser bilíngue? Se você corteja contribuidores globais, sim — mantenha a versão canônica em inglês (a língua de facto do open source) e forneça traduções. O guia de contribuição do freeCodeCamp é uma ótima referência: é traduzido para dezenas de idiomas e usa a convenção de README de um link por locale no topo.

CONTRIBUTING.md ou uma página de wiki? O arquivo no repo vence. Ele versiona junto com o código, o GitHub auto-descobre em issues e PRs, ferramentas de IA o indexam, e forks o carregam consigo. Wikis são ótimos para notas evolutivas, mas as regras de contribuição pertencem junto do código-fonte.