Una plantilla de reporte de error que los desarrolladores sí leerán
Una plantilla de reporte de error para copiar, para qué sirve cada parte y los hábitos que convierten una queja vaga en un ticket que un desarrollador puede corregir.
Hay dos frases que les cuestan a los equipos de software más tiempo del que merecen. La primera es «en mi máquina funciona». La segunda es «¿puedes enviar más detalles?».
Las dos frases son el síntoma de un reporte de error al que le faltaba algo. Quien lo reportó vio el problema con claridad. El desarrollador no puede verlo, así que el ticket queda en espera, quien lo reportó pasa a otras tareas y, cuando llega la respuesta, ya pocos recuerdan los detalles.
La solución no es un reporte más largo. Es un reporte con las partes adecuadas, en un formato que se pueda leer de un vistazo. Aquí tienes una plantilla, para qué sirve cada parte y algunos hábitos que hacen que funcione.
La plantilla, lista para pegar
Cópiala en el campo de descripción de tu tracker o en una plantilla que comparta tu equipo.
``` Título: [Área] Qué falla, en pocas palabras
Pasos para reproducir
- Dónde empiezas (página, pantalla, comando)
- Qué haces
- Qué haces a continuación
- El paso en el que falla
Esperado Lo que debería haber pasado.
Real Lo que pasó en su lugar, incluido el mensaje que apareció.
Entorno Versión o compilación, plataforma, navegador o sistema operativo, tipo de cuenta y con qué frecuencia ocurre.
Pruebas Fragmento del log, captura de pantalla, id de solicitud o una grabación breve.
Severidad y motivo Lo grave que es y a quién afecta.
Relacionados Tickets que parecen similares o que tocan la misma área. ```
Parece un formulario, y esa es la idea. Un desarrollador que abre un ticket con esta forma sabe dónde buscar cada respuesta antes de leer una sola palabra.
Por qué cada parte se gana su lugar
El título es un síntoma, no una teoría. «El total del pago ignora el plan anual después de aplicar un código promocional» le dice a quien hace el triaje exactamente dónde mirar. «Error de precios» no le dice nada. Una etiqueta como [Checkout] al principio ayuda a recorrer una lista larga y a agrupar los tickets que van juntos.
Los pasos van numerados y empiezan en un punto al que un desconocido pueda llegar. Indica los valores reales que usaste, como el código promocional o el plan, porque a los errores les encantan las entradas concretas. Luego haz algo que la mayoría se salta: ejecuta tus propios pasos una vez más antes de registrar el ticket. Si el error no se repite, dilo y describe con qué frecuencia ocurrió. Esa honestidad le ahorra una tarde a un desarrollador.
Esperado y Real zanjan la discusión desde el principio. Sin Esperado, el desarrollador tiene que adivinar qué querías. Sin Real, tiene que adivinar qué viste. Dos líneas breves eliminan dos suposiciones.
El entorno responde a la primera pregunta que hace un desarrollador. ¿En qué compilación pasó? La versión le indica si el problema sigue existiendo en el código que tiene abierto. Añade la plataforma y algún ajuste de la cuenta que pueda cambiar el comportamiento, y di con qué frecuencia ocurre. Un problema que aparece todas las veces y uno que aparece de vez en cuando llevan a investigaciones distintas.
Las pruebas valen más que una descripción. Un log recortado con la línea de error y unas cuantas líneas alrededor vale más que un párrafo de explicación. Una captura de pantalla debe mostrar lo suficiente de la pantalla como para ver dónde estás. Antes de adjuntar nada, busca datos personales y secretos, como direcciones de correo electrónico y tokens de acceso, y elimínalos.
La severidad necesita un motivo. «Alta» a secas es una opinión. «Alta: un cliente de pago ve un total incorrecto» permite al equipo priorizar el ticket frente a todo lo demás que hay en la cola.
Un ejemplo completo
Esta es la plantilla con un caso real.
``` Título: [Checkout] SAVE20 aplica el precio mensual después de cambiar a anual
Pasos para reproducir
- Añade el plan Pro al carrito (mensual)
- Cambia el periodo de facturación a anual
- Aplica el código promocional SAVE20
- Mira el resumen del pedido
Esperado 20% de descuento sobre el precio anual.
Real 20% de descuento sobre el precio mensual, mostrado como total anual.
Entorno Producción, web, compilación 2.14.1, ocurre todas las veces.
Pruebas TypeError: plan.period is undefined at applyPromo (pricing.ts:88)
Severidad y motivo Alta: un cliente de pago ve un total incorrecto. ```
Fíjate en lo que puede hacer un desarrollador con esto en el primer minuto. Conoce el área, puede seguir los pasos y la línea de error apunta a un archivo. No hace falta ninguna pregunta de seguimiento.
Hábitos que mantienen útiles los reportes
Los pequeños hábitos importan más que una plantilla perfecta.
- Un error por ticket. Dos problemas en un mismo reporte se corrigen en momentos distintos, así que regístralos por separado y vincúlalos.
- Busca antes de registrar. Puede que alguien ya haya reportado el mismo problema. Añadir tus pruebas a ese ticket mantiene toda la historia en un solo lugar.
- Di qué probaste. Si recargar la página, usar otro navegador u otra cuenta cambia el resultado, es una pista que merece una línea.
- Mantén un tono neutro. Un reporte no es lugar para la frustración. Los hechos se corrigen antes que los sentimientos.
- Actualiza el ticket cuando sepas más. Un nuevo número de compilación o unos pasos más acotados son valiosos, aunque sea un día después.
Dónde encaja BugIt
Es fácil estar de acuerdo con escribir con este formato y difícil hacerlo al final de un día largo. Ese es el hueco que cubre BugIt. BugIt es un agente de control de calidad que funciona en el asistente que ya usas. Describes lo que falló en una frase rápida, sin pulir y BugIt redacta el reporte con el vocabulario de tu equipo: título, pasos, esperado y real, severidad y las pruebas que le diste. Oculta los datos personales comunes, en la medida de lo posible, así que lee el borrador antes de que nada salga de él. Tú revisas cada borrador antes de que se registre, y no se escribe nada en tu tracker hasta que escribas FILE IT.
Puedes ver cómo funciona en bugit.dev y encontrar más información sobre el producto en taskivator.com/bugit.
En resumen
Un buen reporte de error responde a las preguntas del desarrollador antes de que las haga: dónde, cómo, qué esperabas, qué pasó, en qué compilación y lo grave que es. Usa la plantilla, comprueba tus pasos una vez, adjunta pruebas que hayas recortado y dale un motivo a tu severidad. Los pocos minutos que inviertas volverán en forma de correcciones que llegan antes.