Escribir un informe de error útil

Objetivo

El informe contiene todo lo que necesita quien lo recibe —desarrollador, operador o agente— para reproducir el error en el primer intento y poder clasificarlo, y nada que tenga que descartar antes.

Requisitos previos

El error se ha observado al menos una vez de forma directa; se conoce el entorno (versión, sistema operativo, navegador o entorno de ejecución, configuraciones que se apartan del valor por defecto).

Pasos

1. Buscar primero: ¿ya existe el informe? En ese caso, conviene ampliarlo allí en lugar de abrir uno segundo.
2. Redactar el título como una frase con el síntoma y la condición: «La exportación falla con UnicodeEncodeError en nombres de archivo con diéresis», no «La exportación no funciona».
3. Indicar el entorno: versión del producto o commit, sistema operativo, entorno de ejecución o navegador con su versión, configuraciones relevantes. Lo que se aparta del valor por defecto pertenece aquí.
4. Presentar los pasos para reproducirlo como una lista numerada, cada uno con exactamente una acción, partiendo de un estado inicial conocido (instalación limpia, archivo de ejemplo adjunto). La guía de Mozilla (citada) exige precisamente esta separación entre «Steps to Reproduce», «Expected Results» y «Actual Results».
5. Resultado esperado y resultado real, cada uno en una frase; el mensaje de error de forma literal y completa (la traza de pila como bloque de código, no como captura de pantalla), extracto del registro con marca de tiempo.
6. Reducir el caso en la medida en que el tiempo lo permita: eliminar pasos y datos hasta que el error desaparezca, y deshacer la última eliminación. El patrón de Stack Overflow «minimal, complete, reproducible» es la referencia; a veces la causa ya se vuelve visible al reducir el caso.
7. Frecuencia e impacto: siempre u ocasional, desde cuándo, cuántas personas afectadas, si existe una forma de evitarlo.
8. Las hipótesis sobre la causa van en una sección aparte llamada «Hipótesis», claramente separada de las observaciones. Sin valoraciones ni reproches.
9. Antes de enviarlo, leerlo como si no se conociera el proyecto: ¿falta un archivo, un comando, una versión?

Resultado esperado

Quien lo recibe reproduce el error sin necesidad de preguntar y puede priorizarlo; el informe se convierte más tarde en una prueba de regresión, porque los pasos y la expectativa ya están formulados.

Límites y base de verificación

Algunos errores no se pueden reproducir de forma determinista (comportamiento temporal, carga, concurrencia); en ese caso, la frecuencia, los momentos y las condiciones de la observación deben figurar en el informe. Los datos confidenciales en los anexos y registros deben eliminarse antes. La estructura sigue las guías citadas; no se hacen afirmaciones sobre los tiempos de resolución.