Um bom issue no GitHub dá ao mantenedor tudo o que precisa para reproduzir o seu problema e nada que não precise. Antes de abrir um, pesquise os issues existentes; depois use o modelo de issue do repositório, escreva um título específico e inclua um exemplo mínimo reproduzível, as suas versões exatas e o que esperava versus o que de facto aconteceu. Mantenha-se num problema por issue, formate-o com blocos de código markdown e tenha paciência – a maioria dos mantenedores são voluntários. Um issue que alguém consegue reproduzir em dois minutos é um issue que é corrigido.
Como Escrever um Bom Issue no GitHub: Passo a Passo
- Pesquise primeiro os issues abertos e fechados. O seu bug pode já estar reportado, corrigido ou explicado – comente aí em vez de abrir um duplicado.
- Veja o CONTRIBUTING.md e os modelos de issue. Muitos projetos encaminham perguntas para as Discussions e reservam os issues para bugs e funcionalidades.
- Escolha o modelo certo e um só problema. Escolha “bug report” ou “feature request” e abra um issue separado para cada problema distinto.
- Escreva um título específico. Resuma o sintoma real, como uma boa mensagem de commit – e não “Não funciona”.
- Acrescente um exemplo mínimo reproduzível. Forneça o menor snippet executável, repositório de exemplo ou passos exatos que despoletam o bug.
- Indique o comportamento esperado vs. o real e o seu ambiente. Inclua a versão exata do pacote, o SO e o runtime, mais o erro completo ou os logs num bloco de código.
- Submeta e depois mantenha-se responsivo. Responda às perguntas de seguimento do mantenedor para que o issue não fique parado.
O Que Fazer e o Que Evitar
Fazer:
- Pesquisar os issues abertos e fechados antes de abrir um.
- Seguir o modelo de issue e o guia de contribuição do repositório.
- Escrever um issue claro e específico por problema.
- Incluir um exemplo mínimo reproduzível e as versões exatas.
- Usar blocos de código markdown para código, logs e stack traces.
Evitar:
- Abrir um duplicado sem verificar primeiro.
- Abrir um issue vago do tipo “não funciona” sem reprodução.
- Juntar vários bugs não relacionados num só issue.
- @mencionar ou enviar DM aos mantenedores a exigir uma correção rápida.
- Amontoar comentários “+1” ou “também me acontece” – use antes uma reação 👍.
Pesquise Antes de Abrir
Os issues abertos são apenas metade do quadro – pesquise também os issues fechados. Um issue fechado contém muitas vezes a correção, a solução temporária ou a razão do mantenedor para “won’t fix”. Se encontrar um issue aberto que corresponde, acrescente aí os seus detalhes de reprodução ou ambiente em vez de abrir um duplicado; isso consolida o sinal que os mantenedores usam para priorizar. Use a pesquisa de issues do GitHub com qualificadores como is:issue o texto do seu erro para cortar o ruído.
Use o Modelo de Issue (e o Canal Certo)
A maioria dos repositórios estabelecidos inclui modelos de issue – um formulário de bug report, um formulário de feature request e, por vezes, uma opção de issue em branco que está deliberadamente desativada. Preencha o modelo por completo em vez de apagar os campos; cada campo existe porque os mantenedores se cansaram de o pedir.
Antes disso, dê uma vista de olhos ao CONTRIBUTING.md. Muitos projetos enviam perguntas de utilização para as 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. Publicar uma pergunta de “como fazer” como issue nesses repositórios costuma resultar apenas no seu encerramento com uma ligação para o sítio certo.
O Coração de um Bom Issue: Um Exemplo Reproduzível
Tudo o resto é secundário em relação a esta única pergunta: o mantenedor consegue reproduzir o seu problema? Dê-lhe um exemplo mínimo reproduzível – o menor snippet executável, repositório de exemplo ou sequência exata de passos que despoleta o bug numa instalação limpa. “Às vezes rebenta” não é acionável; “executar npm test num clone novo deste repro de 15 linhas lança o stack trace abaixo” é.
Se está a reportar um bug em vez de pedir uma funcionalidade, coloque o seu exemplo diretamente no nosso modelo de reporte de bug – os seus campos “Passos para reproduzir” e “Ambiente” foram feitos exatamente para isto.
Inclua Versões e Ambiente
“Latest” não é uma versão. Indique a versão exata do pacote (ou o SHA do commit), o sistema operativo e a versão da linguagem ou do runtime – v2.4.1, macOS 14.5, Node 20.11. Os bugs são frequentemente específicos de uma versão, e um mantenedor que não consegue saber em que versão está vai desperdiçar uma ida e volta só a perguntar. Cole a mensagem de erro completa e quaisquer logs relevantes; um erro truncado costuma esconder a linha que realmente importa.
Formate a Sério
Os issues do GitHub são em markdown, por isso use-o. Envolva código, comandos e stack traces em blocos delimitados por três crases com uma indicação de linguagem para destaque de sintaxe. Comprima logs muito longos dentro de um bloco <details> para que o issue continue legível. Identifique as partes principais – Esperado, Real, Passos para reproduzir – e ligue a linhas de código específicas com permalinks (prima y no GitHub para obter um URL fixado a um commit). Um issue limpo e fácil de percorrer é triado mais depressa do que um muro de texto.
Lembre-se de Quem Está do Outro Lado
A maioria dos mantenedores são voluntários não pagos que trabalham no projeto nos tempos livres, e isso molda a etiqueta. Não os @mencione nem lhes envie DM a exigir uma correção, e não acrescente comentários do tipo “alguma atualização?” que só geram ruído. Dispense por completo os “+1” e os “também me acontece” – acrescente uma reação 👍 ao issue original para que os mantenedores possam avaliar a procura sem uma enxurrada de notificações. Comente apenas quando tiver algo novo: outra reprodução, um ambiente diferente ou uma solução temporária.
E se suspeitar de uma vulnerabilidade de segurança, não abra de todo um issue público. Use o reporte de segurança privado do repositório – normalmente uma política SECURITY.md ou o separador “Report a vulnerability” do GitHub – para que a falha não seja divulgada antes de ser corrigida.
A Fórmula Continua a Valer
Um ótimo issue no GitHub é apenas a fórmula do Salte a Pergunta no contexto de um programador:
- A sua situação – o projeto, a versão e o ambiente que está a usar
- O seu reporte ou pedido específico – o bug ou a funcionalidade exata, num título claro
- Detalhes relevantes – um exemplo mínimo reproduzível, o comportamento esperado vs. o real e o erro completo
Dê aos mantenedores um problema que consigam reproduzir e terá feito 90% do trabalho para que seja corrigido.
A fazer uma pergunta de “como fazer” em vez de reportar um bug? O nosso guia do Stack Overflow cobre esse caso. Para os princípios universais por trás de cada plataforma, veja o nosso guia completo para fazer perguntas melhores online.