Uma boa issue no GitHub dá ao mantenedor tudo o que ele precisa para reproduzir seu problema e nada do que ele não precisa. Antes de abrir uma, pesquise as issues existentes; depois use o template de issue do repositório, escreva um título específico e inclua um exemplo mínimo reproduzível, suas versões exatas e o que você esperava versus o que de fato aconteceu. Mantenha um problema por issue, formate com cercas de código markdown e tenha paciência – a maioria dos mantenedores é voluntária. Uma issue que alguém consegue reproduzir em dois minutos é uma issue que é corrigida.
Como Escrever uma Boa Issue no GitHub: Passo a Passo
- Pesquise as issues abertas e fechadas primeiro. Seu bug pode já ter sido reportado, corrigido ou explicado – comente lá em vez de abrir uma duplicata.
- Confira o CONTRIBUTING.md e os templates de issue. Muitos projetos direcionam perguntas para o Discussions e reservam as issues para bugs e funcionalidades.
- Escolha o template certo e um único problema. Selecione “bug report” ou “feature request” e abra uma issue separada para cada problema distinto.
- Escreva um título específico. Resuma o sintoma real, como uma boa mensagem de commit – não “Não funciona.”
- Adicione um exemplo mínimo reproduzível. Forneça o menor trecho executável, um repositório de exemplo ou os passos exatos que disparam o bug.
- Declare o comportamento esperado vs. o real e seu ambiente. Inclua a versão exata do pacote, o SO e o runtime, além do erro completo ou logs em um bloco de código.
- Envie e, depois, continue responsivo. Responda às perguntas de acompanhamento do mantenedor para que a issue não fique parada.
O Que Fazer e o Que Não Fazer
Faça:
- Pesquise as issues abertas e fechadas antes de abrir.
- Siga o template de issue e o guia de contribuição do repositório.
- Escreva uma issue clara e específica por problema.
- Inclua um exemplo mínimo reproduzível e versões exatas.
- Use cercas de código markdown para código, logs e stack traces.
Não faça:
- Abrir uma duplicata sem checar antes.
- Abrir uma issue vaga de “não funciona” sem reprodução.
- Juntar vários bugs sem relação em uma única issue.
- Usar @menção ou DM para mantenedores exigindo uma correção rápida.
- Acumular comentários de “+1” ou “eu também” – use uma reação 👍 em vez disso.
Pesquise Antes de Abrir
As issues abertas são só metade da figura – pesquise também as issues fechadas. Uma issue fechada frequentemente contém a correção, a solução alternativa ou o motivo do mantenedor para “não vamos corrigir”. Se você encontrar uma issue aberta que combina, adicione lá seus detalhes de reprodução ou seu ambiente em vez de abrir uma duplicata; isso consolida o sinal que os mantenedores usam para priorizar. Use a busca de issues do GitHub com qualificadores como is:issue texto do seu erro para cortar o ruído.
Use o Template de Issue (e o Canal Certo)
A maioria dos repositórios estabelecidos vem com templates de issue – um formulário de bug report, um de feature request e, às vezes, uma opção de issue em branco que está deliberadamente desligada. Preencha o template por completo em vez de apagar as instruções; cada campo está ali porque os mantenedores cansaram de ter que pedir por ele.
Antes disso, dê uma olhada no CONTRIBUTING.md. Muitos projetos mandam perguntas de uso para o GitHub Discussions, um fórum da comunidade ou o Stack Overflow, e mantêm o rastreador de issues estritamente para bugs e pedidos de funcionalidades. Postar uma pergunta de “como faço” como issue nesses repositórios geralmente só faz com que ela seja fechada com um link para o lugar certo.
O Coração de uma Boa Issue: Um Exemplo Reproduzível
Todo o resto é secundário diante desta única pergunta: o mantenedor consegue reproduzir o seu problema? Dê a ele um exemplo mínimo reproduzível – o menor trecho executável, repositório de exemplo ou sequência exata de passos que dispara o bug em um ambiente limpo. “Às vezes ele quebra” não é acionável; “rodar npm test em um clone novo deste repro de 15 linhas lança o stack trace abaixo” é.
Se você está reportando um bug em vez de pedir uma funcionalidade, coloque seu exemplo direto no nosso modelo de relatório de bug – seus campos de “Passos para reproduzir” e “Ambiente” foram feitos exatamente para isso.
Inclua Versões e Ambiente
“Mais recente” não é uma versão. Informe a versão exata do pacote (ou o SHA do commit), o sistema operacional e a versão da linguagem ou do runtime – v2.4.1, macOS 14.5, Node 20.11. Bugs são frequentemente específicos de uma versão, e um mantenedor que não consegue saber em qual release você está vai desperdiçar uma ida e volta só perguntando. Cole a mensagem de erro completa e quaisquer logs relevantes; um erro truncado normalmente esconde a linha que de fato importa.
Formate Como Se Levasse a Sério
Issues do GitHub são markdown, então use. Coloque código, comandos e stack traces em cercas de três crases com uma dica de linguagem para destaque de sintaxe. Recolha logs muito longos dentro de um bloco <details> para que a issue continue legível. Rotule as partes-chave – Esperado, Real, Passos para reproduzir – e aponte para linhas específicas de código com permalinks (pressione y no GitHub para obter uma URL fixada no commit). Uma issue limpa e fácil de escanear é triada mais rápido do que um muro de texto.
Lembre-se de Quem Está do Outro Lado
A maioria dos mantenedores é de voluntários não remunerados trabalhando no projeto no tempo livre, e isso molda a etiqueta. Não use @menção nem DM para exigir uma correção, e não adicione comentários de “alguma novidade?” que só criam ruído. Pule “+1” e “eu também” por completo – adicione uma reação 👍 à issue original para que os mantenedores possam medir a demanda sem uma enxurrada de notificações. Comente apenas quando você tiver algo novo: outra reprodução, um ambiente diferente ou uma solução alternativa.
E se você suspeitar de uma vulnerabilidade de segurança, não abra uma issue pública de jeito nenhum. Use o relato de segurança privado do repositório – normalmente uma política SECURITY.md ou a aba “Report a vulnerability” do GitHub – para que a falha não seja divulgada antes de ser corrigida.
A Fórmula Continua Valendo
Uma ótima issue no GitHub é apenas a fórmula do Skip The Ask no contexto de um desenvolvedor:
- Sua situação – o projeto, a versão e o ambiente em que você está rodando
- Seu relato ou pedido específico – o bug ou a funcionalidade exata, em um título claro
- Detalhes relevantes – um exemplo mínimo reproduzível, comportamento esperado vs. real e o erro completo
Dê aos mantenedores um problema que eles consigam reproduzir e você já fez 90% do trabalho rumo à correção.
Fazendo uma pergunta de “como faço” em vez de reportar um bug? Nosso guia do Stack Overflow cobre esse caso. Para os princípios universais por trás de toda plataforma, veja nosso guia completo para fazer perguntas melhores online.