Como escrever um relatório de bug utilizável

Objetivo

O relatório contém tudo de que o destinatário – desenvolvedora, operador ou agente – precisa para reproduzir e classificar o erro logo na primeira tentativa, e nada que ele tenha de descartar primeiro.

Pré-requisitos

O erro foi observado pelo menos uma vez por você mesmo; o ambiente é conhecido (versão, sistema operacional, navegador ou runtime, configurações que diferem do padrão).

Passos

1. Pesquisar antes: o relatório já existe? Nesse caso, complemente-o em vez de abrir um segundo.
2. Título como frase com sintoma e condição: «A exportação falha com UnicodeEncodeError em nomes de arquivo com trema», e não «Exportação quebrada».
3. Informar o ambiente: versão do produto ou commit, sistema operacional, runtime ou navegador com versão, configurações relevantes. O que difere do padrão deve constar aqui.
4. Passos para reproduzir como lista numerada, cada um com exatamente uma ação, partindo de um estado inicial conhecido (instalação limpa, arquivo de exemplo em anexo). A diretriz da Mozilla (citada) exige exatamente essa separação entre «Steps to Reproduce», «Expected Results» e «Actual Results».
5. Resultado esperado e resultado real em uma frase cada; a mensagem de erro literal e completa (stack trace como bloco de código, não como captura de tela), trecho de log com carimbo de data e hora.
6. Reduzir enquanto houver tempo: remover passos e dados até o erro desaparecer e então desfazer a última remoção. O padrão do Stack Overflow «minimal, complete, reproducible» é a referência; às vezes a causa já fica visível durante a redução.
7. Frequência e impacto: sempre ou ocasionalmente, desde quando, quantas pessoas são afetadas, se existe um contorno.
8. Suposições sobre a causa numa seção própria, «Suposição», claramente separada das observações. Sem julgamentos nem acusações.
9. Antes de enviar, ler como se não conhecesse o projeto: falta algum arquivo, comando ou versão?

Resultado esperado

O destinatário reproduz o erro sem fazer perguntas e consegue priorizá-lo; mais tarde o relatório serve de teste de regressão, pois os passos e a expectativa já estão formulados.

Limites e base de verificação

Alguns erros não podem ser reproduzidos de forma determinística (comportamento temporal, carga, concorrência); nesse caso, o relatório deve incluir a frequência, os momentos e as condições da observação. Dados confidenciais em anexos e logs devem ser removidos antes. A estrutura segue as diretrizes citadas; não se fazem afirmações sobre prazos de tratamento.