Como escrever um CONTRIBUTING.md

É o arquivo em que o projeto explica como quer receber ajuda. A documentação do GitHub diz que as diretrizes de contribuição ajudam as pessoas a enviar pull requests bem formados e issues úteis, e reduzem trabalho rejeitado ou refeito. Para quem chega pela primeira vez, é o arquivo mais importante depois do README: ele diz o que fazer antes de escrever uma linha de código.

O CONTRIBUTING pode ficar na raiz do repositório, em docs ou em .github. Havendo mais de um, o GitHub procura primeiro em .github, depois na raiz e por último em docs. Quando alguém abre uma issue ou um pull request, vê um link para o arquivo, que também aparece na página de contribuição do repositório. Se o arquivo se chama CONTRIBUTING.md, o GitHub mostra uma aba "Contributing" na visão geral do repositório e um link na barra lateral.

A documentação do GitHub sugere três coisas: os passos para criar boas issues e pull requests, links para documentação externa, listas de e-mail ou o código de conduta, e as expectativas de comportamento da comunidade. A Open Source Guides acrescenta, em seu guia de boas práticas, o que dizer sobre o processo: como as contribuições são revisadas, quais tipos você aceita, em quanto tempo costuma responder e quanto tempo você tem para dar. Reunindo as duas, um bom arquivo tem estes blocos:

1. Antes de começar: ler o código de conduta e procurar nas issues se a ideia já existe.
2. Como relatar um problema: o que escrever em uma issue (veja como abrir uma boa issue).
3. Como propor uma mudança: fork, clone, branch (veja o passo a passo).
4. Como preparar o ambiente e rodar os testes: os comandos, de verdade.
5. Padrão de commits: por exemplo, Conventional Commits.
6. Como abrir o pull request e o que esperar da revisão, inclusive o prazo.
7. Onde tirar dúvidas.

O CONTRIBUTING fica mais curto quando modelos fazem parte do trabalho. Os modelos de issue ficam em .github/ISSUE_TEMPLATE, em Markdown ou em formulários .yml; os de pull request podem ficar na raiz, em docs ou em .github. Ambos precisam estar na branch padrão para aparecer. A Open Source Guides cita modelos e um guia de contribuição como forma de filtrar pedidos de baixa qualidade antes que cheguem.

Cada regra extra é uma barreira. A Open Source Guides diz isso: padrões simples. Se uma exigência não pode ser conferida por um teste automático nem pela revisão, pense se ela precisa estar no arquivo.

Para o projeto listaki, as respostas ao formulário do gerador de CONTRIBUTING seriam: contribuição por fork, repositório msouza/listaki, ambiente npm install, testes npm test, commits no padrão Conventional Commits, issue antes de mudanças grandes e prazo de uma semana. O gerador devolve um arquivo com as seções "Antes de começar", "Como relatar um problema", "Como propor uma mudança", "Preparar o ambiente", "Conferir antes de enviar", "Mensagens de commit", "Abrir o pull request" e "O que acontece depois", com os comandos de git já escritos com o seu repositório. Você copia ou baixa, ajusta o que for específico do projeto e faz o commit na raiz.