En el software científico y de ingeniería, la mayor parte de la frustración no proviene de problemas difíciles: proviene de declaraciones de problemas poco claras. Un ticket que «suena mal» en realidad podría describir una capacidad faltante. Una solicitud de una «pequeña mejora» podría estar enmascarando un defecto que daña los resultados. Cuando los equipos clasifican erróneamente las entradas, pierden el tiempo: los desarrolladores investigan los errores fantasmas, los investigadores esperan las características que nunca fueron de alcance y las prioridades se desviaron.
Esta guía lo ayuda a decidir rápidamente si algo es un informe de error o una solicitud de función, y muestra cómo escribir cada uno para que el equipo pueda actuar en consecuencia. El objetivo es simple: menos comentarios de ida y vuelta, triaje más rápido y menos sorpresas en los lanzamientos.
Por qué es importante la distinción
Los informes de errores y las solicitudes de funciones se manejan de manera diferente en la mayoría de los flujos de trabajo (trac, jira, problemas de github, redmine, etc.). Tienen una urgencia diferente, diferentes criterios de aceptación y diferentes formas de probar y cerrar el bucle.
- Un informe de error generalmente tiene una expectativa de corrección: el software viola su propio contrato, documentación o comportamiento establecido.
- Una solicitud de función solicita un nuevo comportamiento: algo que el software no promete hacer actualmente, incluso si sería útil.
Cuando etiqueta el ticket correctamente, el triaje se vuelve más fácil: los mantenedores pueden reproducir, priorizar y asignar trabajo sin adivinar qué «debería» suceder.
Las definiciones centrales
¿Qué es un informe de error?
Un error es cuando el sistema se comporta incorrectamente en comparación con un punto de referencia acordado. Ese punto de referencia puede ser:
- Documentación o una interfaz publicada (contrato API)
- Comportamiento estable anterior (una regresión)
- Corrección científica (por ejemplo, leyes de conservación, invariantes esperados, consistencia unitaria)
- Requisitos claramente establecidos (incluyendo pruebas o especificaciones)
En resumen: un informe de error describe un error que debe solucionarse para restaurar la corrección.
¿Qué es una solicitud de función?
Una solicitud de función propone una capacidad o mejora que haría que el sistema sea más útil, flexible o eficiente, pero no se requiere para la corrección del comportamiento actual. Los ejemplos incluyen:
- Apoyar un nuevo tipo de condición de contorno
- Agregar un exportador para un nuevo formato de archivo
- Mejorar el rendimiento más allá de los objetivos actuales
- Agregar opciones de UI/CLI que aún no existen
En resumen: una solicitud de función describe algo nuevo que el sistema debería hacer.
Lista de verificación de decisión rápida
Si solo recuerdas una regla, usa esta:
- Si el software rompe una promesa, es un error.
- Si quieres una nueva promesa, es una característica.
Hágase estas preguntas:
- ¿Alguna vez funcionó antes en el mismo escenario? En caso afirmativo, probablemente un error (posiblemente una regresión).
- ¿Hay documentación que indique que el comportamiento debería funcionar? Si es así, error.
- ¿El comportamiento es ambiguo y estás proponiendo lo que debería ser? probablemente una característica (o una aclaración de especificaciones primero).
- ¿El problema es que no puedes hacer algo en absoluto, pero nada está «incorrecto» con las salidas existentes? probablemente una característica.
- ¿Produce resultados incorrectos, fallas, datos dañados o viola las restricciones físicas? bicho
Comparación lado a lado
| Aspecto | Informe de error | Petición de función |
|---|---|---|
| Significado | algo está mal en comparación con el comportamiento esperado | se desea algo nuevo o mejorado |
| punto de referencia | Documentos, pruebas, versiones anteriores, criterios de corrección | Necesidades del usuario, objetivos de investigación, mejoras de usabilidad |
| Evidencia típica | Pasos de reproducción, registros, salida incorrecta, rastreo de bloqueo | Caso de uso, beneficio, comportamiento propuesto, criterios de aceptación |
| Conductores de prioridad | Gravedad, alcance, frecuencia, riesgo a los resultados | Impacto, demanda, hoja de ruta estratégica, esfuerzo |
| Cómo está “hecho” | solución verificada; pases de prueba; Regresión evitada | especificación implementada; documentado; de extremo a extremo utilizable |
Ejemplos en Computación Científica
Ejemplo 1: Resultados incorrectos debido a la falta de coincidencia de unidades
Ejecuta una simulación y observa que un parámetro documentado como «metros» se trata como «milímetros», cambiando los resultados en 1000 ×. Si la documentación y el código no están de acuerdo, y las salidas son incorrectas para el uso documentado, ese es un informe de error. Su boleto debe incluir el parámetro, donde esté documentado, un caso mínimo y evidencia de desajuste.
Ejemplo 2: necesita un nuevo término PDE o acoplamiento
Desea agregar un término de electromigración a un modelo de transporte existente. El código actual funciona según lo diseñado; Simplemente no incluye esa física. Esa es una solicitud de función. Su ticket debe explicar la ecuación de gobierno, las entradas esperadas y cómo la validaría (referencias o límites analíticos).
Ejemplo 3: «Es demasiado lento»
El rendimiento puede ser cualquiera. Si el código solía ejecutarse en 5 minutos y ahora toma 50 minutos en la misma configuración, eso es un error (una regresión de rendimiento). Si el código siempre ha tomado 50 minutos y desea que tome 5, esa es una solicitud de función (funcionamiento de optimización), a menos que la lentitud provenga de un comportamiento no deseado (como un solucionador atascado debido a un problema de convergencia).
Ejemplo 4: Mensaje de error confuso
Un mensaje de error confuso suele ser una solicitud de función (mejora UX), a menos que el mensaje sea incorrecto o enmascara el error real de una manera que impida el diagnóstico. En muchos equipos, «mejorar mensaje de error» se rastrea como una mejora, no como un error.
Clasificaciones erróneas comunes y cómo solucionarlas
Clasificación errónea: «se bloquea» (pero solo con entrada no válida)
Si el software se bloquea cuando se le da una entrada no válida, podría ser un error si el programa falla con gracia (error claro, no hay archivos dañados). Si se espera bloquear porque la entrada está fuera de las restricciones admitidas y la herramienta ya lo documenta, podría ser una solicitud de mejora para mejorar la validación y los mensajes.
Clasificación errónea: «El resultado se ve mal» (pero las expectativas no están claras)
Si el ticket no define lo que significa «correcto», los mantenedores no pueden decidir el error frente a la función. En ese caso, escriba el boleto como una pregunta más una expectativa propuesta y adjunte pruebas. A menudo, el mejor primer paso es: «aclarar el comportamiento esperado», luego volver a presentarlo como error o característica una vez confirmado.
Clasificación errónea: «Por favor agregue la opción X» (pero el código ya lo admite)
Esto no es una característica ni un error en el comportamiento central; puede ser una brecha de documentación. Si la capacidad existe pero es difícil de descubrir, cree un ticket de documento (o una mejora centrada en la usabilidad).
Cómo escribir un informe de error de alta calidad
Un buen informe de error facilita la reproducción, el diagnóstico y la verificación de la solución.
Plantilla de informe de error
- Resumen: Una oración que describe el comportamiento incorrecto
- Entorno: OS, versión de Python/C++, versión de paquete/commit, versiones de MPI/Solver si es relevante
- Pasos para reproducir: pasos mínimos, archivos de entrada mínimos, fragmento de código mínimo
- Resultado esperado: qué debería suceder y por qué (docs/pruebas/comportamiento anterior)
- Resultado real: lo que sucede en su lugar (registros, seguimiento de pila, capturas de pantalla, diferencial de salida)
- Impacto: Gravedad (Crash, Ciencias Incorrectas, IU Menor), Frecuencia, Solución Si la tiene
Ejemplo de informe de error (corto)
Resumen: El ejemplo de difusión falla con Dirichlet BC en la cuadrícula 3D.
- Esperado: La simulación se ejecuta y produce valores de campo estables como en 2D.
- Actual: Solver diverge después de n pasos; Los valores se convierten en NaN.
- Evidencia: Proporcione un script mínimo, valores de parámetros y salida de registro.
Cómo escribir una solicitud de función sólida
Una fuerte solicitud de función se lee como un mini diseño. Nota: explica por qué la capacidad es importante, cómo se ve «hecho» y cómo lo verificará.
Plantilla de solicitud de función
- Declaración del problema: lo que no puedes hacer hoy
- Caso de uso: quién lo necesita y por qué (flujo de trabajo de investigación, módulo de enseñanza, canalización de producción)
- Solución propuesta: comportamiento de alto nivel, cambios de interfaz de usuario/API, valores predeterminados
- Criterios de aceptación: lo que debe ser cierto para considerarlo completo
- Validación: cómo probar (benchmarks, tests unit, soluciones analíticas, suite de regresión)
- Alternativas consideradas: soluciones alternativas u otros enfoques
Ejemplo de solicitud de función (corto)
Solicitud: agregue una opción para exportar el estado de simulación a un formato de visualización estandarizado a intervalos configurables.
- Caso de uso: grandes ejecuciones en HPC donde se necesita una visualización intermedia para el monitoreo.
- Aceptación: Obras de exportación para redes 2D/3D; Incluye metadatos (paso de tiempo, unidades); Sin ralentización importante.
- Validación: comparar campos exportados con matrices en memoria; Asegúrese de que la recarga reproduce el estado dentro de la tolerancia.
Cuando un boleto debe convertirse en dos
Muchos problemas del mundo real mezclan errores y características. Dividirlos a menudo acelera el progreso.
- Si hay un accidente (error) y también un deseo de un mensaje más agradable (característica), presente dos boletos.
- Si hay un problema de corrección (BUG) y también una solicitud para respaldar un nuevo régimen, separe el «comportamiento actual» de la «capacidad de extensión».
- Si la solicitud es «hacerlo más rápido» pero sospecha una regresión, presente un error para la regresión y una función para una mayor optimización.
Dividir boletos permite a los equipos cerrar el error rápidamente y programar la mejora con sensatez.
Consejos de triaje para mantenedores y clientes potenciales
Use etiquetas y un comentario de decisión corta
Cuando un ticket llegue ambiguo, agregue un breve comentario que bloquee la clasificación:
- “Clasificando como error porque el comportamiento contradice la sección de documentación X”.
- «Clasificación como solicitud de función porque esto agrega una nueva capacidad de solucionador que no es compatible actualmente».
Requieren criterios mínimos de aceptación para las características
Las solicitudes de función fallan cuando «hecho» no está claro. Pregunte por los criterios de aceptación temprano: qué salida, qué interfaz, qué pruebas, qué ejemplo. Una característica sin criterios de aceptación es efectivamente un elemento de la lista de deseos.
Convierta las preguntas recurrentes en tareas de documentación
Si múltiples «solicitudes de funciones» son en realidad solicitudes de orientación («¿Cómo hago yo…?»), Capture las como mejoras en los documentos. Esto es especialmente común en las bibliotecas científicas donde existen capacidades pero no son obvias.
Plantillas prácticas que puedes copiar en tickets
Clasificador de una sola línea
Use esto como la primera línea de su descripción de su boleto:
- ERROR: “El comportamiento observado contradice el comportamiento esperado definido por [docs/test/previous version]”.
- Característica: «Nueva capacidad necesaria para admitir [use case], no disponible actualmente».
Criterios de aceptación Set de inicio para funciones
- API: nueva opción/parámetro documentado con valores predeterminados
- Ejemplo: Ejemplo de trabajo mínimo incluido en documentos/ejemplos
- Pruebas: al menos una prueba automatizada cubre el comportamiento principal
- Compatibilidad con versiones anteriores: los scripts existentes continúan ejecutándose sin cambios (o pasos de migración documentados)
Conclusión
Los informes de errores restauran la confianza; Las solicitudes de funciones expanden la capacidad. Ambos son esenciales en el software científico, pero solo tienen éxito cuando están escritos con la intención y la evidencia correctas. Si vincula los errores a un punto de referencia y vincula las características a un caso de uso claro con criterios de aceptación, reducirá la fricción de clasificación, acelerará el desarrollo y hará que las versiones sean más predecibles, lo que en última instancia mejora la velocidad de investigación y la fiabilidad de los resultados.