Como abrir uma boa issue no GitHub

A Open Source Guides indica a issue para três coisas: relatar um erro que você não consegue corrigir, discutir uma ideia e propor uma funcionalidade. Antes de abrir, procure nas issues já existentes, abertas e fechadas: a pergunta que você tem pode já estar respondida, e a mesma ideia repetida só aumenta o trabalho de quem mantém.

Se a issue já existe e é a sua, comente nela em vez de abrir outra. Se você mesmo resolver o problema depois, a mesma página recomenda comentar o resultado e fechar a issue.

A documentação do GitHub lista várias formas de criar uma issue. A mais comum é a aba Issues do repositório e o botão New issue. Se o projeto tiver modelos, você escolhe um (ou uma issue em branco, se nenhum servir). Também dá para criar a partir de um comentário, pela opção "Reference in new issue", ou a partir de uma ou mais linhas de código, marcando-as e usando o menu de opções. Pela linha de comando:

gh issue create --title "Título curto" --body "Descrição do problema"

Os modelos de issue ficam na pasta .github/ISSUE_TEMPLATE, em Markdown ou, nos formulários, em arquivos .yml. Eles precisam estar na branch padrão para aparecer.

A Open Source Guides pede contexto, concisão e conversa em canal público. Para um defeito, isto costuma bastar (é prática comum, não regra oficial):

• Título que diga o problema em uma linha, com o nome da parte afetada.
• O que você esperava e o que aconteceu.
• Passos para repetir, do começo ao fim, de preferência com o menor exemplo possível.
• Ambiente: versão do projeto, do sistema e do que mais importar.
• Mensagem de erro completa, copiada como texto.

Para uma proposta, explique o problema antes da solução e diga se você pode implementar. A documentação do GitHub recomenda abrir a issue e descrever a sua abordagem antes de gastar muito tempo com código em mudanças maiores.

A página da Open Source Guides resume bem: não saber algo é normal, mas mostre que você tentou. Conte o que já pesquisou. Seja objetivo e paciente: se não houver resposta depois de cerca de uma semana, a recomendação é cobrar com educação, em público, no mesmo lugar.

A segunda versão permite que quem mantém reproduza o erro em um minuto. Se o repositório tem um modelo de issue, use-o; se não tem, copie essa estrutura. Gerar também um CONTRIBUTING.md para o seu projeto ajuda quem chega a abrir issues melhores.