Cómo reportar un bug correctamente con ejemplos reales

Un buen reporte de bug debe contener toda la información necesaria para que la persona que va a arreglarlo entienda el problema y pueda reproducirlo por sí misma, sin tener que adivinar ni volver a preguntar. Los elementos esenciales son los siguientes. Primero, un título claro y específico que resuma el problema concreto en una frase, de modo que se identifique de un vistazo en una lista de incidencias, evitando títulos vagos como no funciona. Segundo, y lo más importante, los pasos para reproducir el error, numerados y exactos, partiendo de un estado conocido, de manera que cualquiera pueda seguirlos y llegar al mismo fallo; sin esta sección, el reporte es prácticamente inútil. Tercero, el resultado esperado, que describe qué debería haber ocurrido según el comportamiento correcto. Cuarto, el resultado obtenido, que describe qué ocurrió realmente; el contraste entre lo esperado y lo obtenido es, de hecho, la definición precisa del defecto. Quinto, el entorno en que se produjo, especificando datos como el navegador y su versión, el sistema operativo, el dispositivo y la versión de la aplicación, ya que muchos errores solo se manifiestan en combinaciones concretas. Y sexto, la evidencia, como capturas de pantalla, vídeos o los mensajes de error exactos de la consola o los registros, que muestran el problema y aceleran su diagnóstico. Un reporte que reúne estos elementos permite reproducir y corregir el bug sin ida y vuelta, mientras que la ausencia de cualquiera de ellos obliga a quien arregla a perder tiempo pidiendo aclaraciones o, peor, a cerrar el reporte como no reproducible aunque el problema exista realmente.

Los pasos para reproducir son la sección más importante de un reporte de bug porque son lo que permite a quien va a arreglarlo ver el problema con sus propios ojos, que es casi siempre condición indispensable para poder diagnosticarlo y corregirlo. Un desarrollador no puede arreglar de forma fiable algo que no puede observar ocurrir, y sin unos pasos claros y exactos que lleven al error de manera repetible, se ve obligado a adivinar en qué circunstancias se produce, lo que suele derivar en una de dos situaciones indeseables: o bien una larga cadena de preguntas y respuestas para reconstruir lo que hizo quien reportó, consumiendo el tiempo de ambos, o bien el cierre del reporte con la etiqueta de no reproducible, porque el desarrollador no logró que el fallo apareciera y no tiene forma de avanzar. Para que los pasos cumplan su función deben reunir varias características: partir de un estado inicial conocido y claro, de modo que no dependan de condiciones previas implícitas; estar numerados y ser precisos, indicando exactamente qué acción realizar en cada paso, incluidos los datos concretos que se introducen; y ser completos, sin saltarse ninguna acción que resulte necesaria para llegar al error. Una buena prueba de calidad consiste en imaginar que otra persona, sin ningún contexto, sigue esos pasos al pie de la letra: si llega al mismo error, los pasos son buenos; si necesita interpretar o rellenar huecos, hay que mejorarlos. Invertir un poco más de cuidado en escribir bien esta sección ahorra, casi siempre, mucho más tiempo del que cuesta, porque convierte un problema difuso en algo concreto y accionable.

La severidad y la prioridad son dos clasificaciones distintas de un bug que se confunden con frecuencia, y separarlas correctamente es clave para tomar buenas decisiones sobre qué arreglar y cuándo. La severidad mide el impacto técnico del defecto, es decir, cuánto daño causa al sistema o a la experiencia cuando ocurre, y va desde niveles críticos, como una caída completa del sistema o la pérdida de datos, hasta niveles menores o cosméticos, como un elemento visual ligeramente desalineado. La severidad la suele asignar quien reporta el bug, típicamente el equipo de calidad, porque es quien conoce de primera mano el efecto técnico del fallo. La prioridad, en cambio, mide la urgencia de arreglarlo, es decir, si debe resolverse de inmediato o puede esperar, y la decide normalmente la gestión del proyecto o el negocio, porque depende de consideraciones como cuántos usuarios se ven afectados, el impacto comercial o de imagen, y las prioridades generales del producto. La clave es que ambas dimensiones son independientes entre sí, y las cuatro combinaciones posibles tienen sentido. Un bug puede tener severidad alta pero prioridad baja, como una caída en una funcionalidad avanzada que casi nadie utiliza: es técnicamente grave pero no urgente. Y a la inversa, un bug puede tener severidad baja pero prioridad alta, como una errata muy visible o un logotipo incorrecto en la página principal: es trivial desde el punto de vista técnico, pero hay que corregirlo cuanto antes porque lo ve todo el mundo y daña la imagen. Mantener separados estos dos conceptos permite que quien conoce el impacto técnico aporte la severidad y quien conoce el impacto en el negocio decida la prioridad, y que la conversación sobre qué arreglar primero se base en información precisa en lugar de en una única etiqueta confusa.

Un reporte de bug se vuelve inútil cuando no proporciona la información mínima que permite reproducir y entender el problema, obligando a quien lo recibe a adivinar o a iniciar una cadena de preguntas para reconstruir lo que ocurrió. El ejemplo arquetípico de reporte inútil es el que consiste en poco más que no funciona o da error, sin ningún detalle adicional. Este tipo de reporte falla en todo lo esencial: no indica qué parte concreta no funciona, no describe los pasos que llevaron al fallo, no dice qué se esperaba que ocurriera ni qué ocurrió realmente, no especifica el entorno, y no aporta ninguna evidencia. El resultado es predecible y frustrante para todos. En el mejor de los casos, se produce un ida y vuelta de aclaraciones que consume tiempo de ambas partes hasta reconstruir la información que debería haber estado desde el principio. En el peor, y muy habitual, el desarrollador no logra reproducir el problema con la escasa información disponible y cierra el reporte como no reproducible, con lo que el defecto queda sin corregir aunque exista de verdad, y a veces reaparece más tarde generando aún más trabajo. Otros patrones que hacen inútil o poco útil un reporte incluyen mezclar varios bugs distintos en una sola incidencia, lo que impide seguirlos y cerrarlos de forma ordenada; omitir el entorno cuando el bug depende de él; describir la interpretación de la causa en lugar de los hechos observados, introduciendo suposiciones que pueden despistar; y usar títulos vagos que no permiten identificar el problema en una lista. En definitiva, un reporte es inútil cuando traslada al lector la carga de averiguar lo que quien reportó ya sabía pero no se molestó en escribir, y evitar esto es precisamente el objetivo de aprender a reportar correctamente.

La regla general y muy recomendable es reportar un único bug por cada reporte o incidencia, y no agrupar varios defectos distintos en uno solo, por más tentador que resulte cuando se encuentran varios problemas a la vez. La razón principal es que cada bug tiene su propio ciclo de vida independiente: se asigna a una persona, se investiga, se corrige, se verifica y se cierra, y muy probablemente en momentos distintos y por personas distintas. Si se meten varios defectos en un mismo reporte, ese ciclo se vuelve inmanejable, porque no se puede cerrar el reporte hasta que todos los problemas estén resueltos, no queda claro cuál de ellos se arregló y cuál sigue pendiente, y el seguimiento se enturbia. Además, distintos bugs pueden tener severidades y prioridades diferentes, corresponder a áreas o componentes distintos del sistema, y requerir a desarrolladores diferentes, todo lo cual choca con la idea de un único reporte compartido. Separar cada defecto en su propio reporte permite, en cambio, priorizarlos de forma individual, asignarlos a quien corresponda, seguir su estado con claridad y mantener un historial limpio de qué se encontró y cómo se resolvió. Sí es legítimo, y a veces útil, relacionar entre sí reportes que estén conectados, por ejemplo enlazándolos o agrupándolos bajo un tema común cuando comparten una causa raíz o forman parte de la misma funcionalidad, siempre que cada uno siga siendo una incidencia independiente. También conviene, antes de crear un reporte, comprobar si el mismo bug ya fue reportado por otra persona para no duplicarlo, en cuyo caso lo apropiado es sumar información al reporte existente en lugar de abrir uno nuevo. En resumen, un reporte, un bug, con relaciones explícitas cuando aporten contexto, es la práctica que mantiene la gestión de defectos ordenada y eficaz.

Los bugs que no se reproducen de forma consistente, a veces llamados intermitentes o esporádicos, son de los más difíciles de gestionar, pero eso no significa que no deban reportarse; al contrario, conviene reportarlos igualmente, aportando toda la información posible aunque sea incompleta, porque a menudo esconden problemas serios y porque los datos parciales de varios reportes pueden ayudar a identificar el patrón. La estrategia consiste en documentar con el máximo detalle todo lo que sí se sabe, aun cuando no se pueda garantizar la reproducción. En primer lugar, hay que ser honesto y explícito sobre la intermitencia, indicando claramente que el bug no siempre ocurre y, si se puede estimar, con qué frecuencia aparece, por ejemplo una de cada varias veces. En segundo lugar, conviene registrar todas las circunstancias conocidas de las veces en que sí ocurrió: qué se estaba haciendo exactamente, en qué entorno, a qué hora, con qué datos, y cualquier factor que pudiera ser relevante como la carga del sistema, la conexión o acciones simultáneas, ya que un patrón oculto puede emerger al comparar varios casos. En tercer lugar, es especialmente valioso capturar toda la evidencia posible en el momento en que ocurre, como registros de error, capturas o vídeos, porque en un bug intermitente esa evidencia recogida en el instante del fallo puede ser la única pista sólida. También ayuda anotar qué se intentó para reproducirlo y no funcionó, para que quien investigue no repita esos caminos. Finalmente, conviene animar al equipo a añadir información cada vez que el bug vuelva a aparecer, tratando el reporte como un lugar donde se acumulan observaciones hasta que el patrón se aclare. Aunque estos reportes no permitan una reproducción inmediata, bien documentados aumentan mucho las probabilidades de que el problema acabe entendiéndose y corrigiéndose.