Enviar una incidencia nueva¶

Redactar un buen informe de incidencia o fallo puede marcar todas las diferencias en la habilidad para solucionar un problema. Aquí mostrados como enviar un buen informe de fallo a BeeWare.

Búsqueda de incidencias existentes¶

Antes de enviar una incidencia nueva, busque en el índice las incidencias existentes que coincidan con la suya. Si hay una incidencia abierta que parece coincidir con tu problema, añade un comentario a esa incidencia con cualquier información adicional sobre tu experiencia. Por ejemplo, si ves el problema en una versión diferente de Python o en un sistema operativo diferente, esa información adicional puede ser útil para determinar el impacto o la causa de un problema.

Si encuentras una incidencia cerrada que parece coincidir con tu problema, comprueba cuándo se cerró esa incidencia. Si se cerró hace muy poco, es probable que el fallo se haya solucionado y se corrija en la próxima versión. Si la incidencia se cerró hace más de 4 meses, es probable que lo que estés experimentando sea un problema diferente, por muy similar que parezca el mensaje de error.

Si no encuentra una incidencia que coincida con lo que está viendo, sería apropiado abrir una incidencia nueva.

Empezar con un debate¶

Antes de enviar una incidencia a GitHub, considera la posibilidad de comenzar con una discusión para preguntar si lo que estás experimentando es realmente un error, o una incidencia con tu configuración o proceso. A menos que estés viendo un comportamiento que contradice directamente el comportamiento documentado, es probable que valga la pena hacer una pregunta antes de ir directamente a enviar un informe de error. Si resulta que has encontrado una incidencia, un tema de discusión puede convertirse fácilmente en un problema.

Iniciar un debate también puede ayudarte a asegurarte de que estás informando de una incidencia en el lugar más adecuado. Aunque hayas experimentado un problema al utilizar BeeWare, el problema podría estar causado por un defecto en un proyecto diferente del ecosistema BeeWare.

Redactar un buen informe de error¶

Si se requiere una incidencia nueva, es importante proporcionar el mayor detalle posible. Un buen informe de fallo incluye toda la información potencialmente relacionada con el fallo, así como el ejemplo de reproducción más pequeño posible.

El ejemplo de reproducción debe ser lo más breve y conciso posible mientras aún exhibe el fallo. Proporcionar un ejemplo masivo dificulta más la resolución de problemas, especialmente si depende de otras bibliotecas, o requiere un conocimiento amplio del comportamiento esperado o la lógica interna del ejemplo.

Necesitamos tantos detalles posibles que pueda proporcionar. Esto incluye, pero definitivamente no se limita a:

Tu versión del sistema operativo, hasta la micro versión (por ejemplo, macOS 15.7.2).
Tu versión de Python, también baja a la micro versión (p.ej. 3.14.1).
Cómo instalaste Python. ¿Lo descargaste de python.org? ¿Usaste Homebrew? ¿uv? ¿pyenv? ¿conda? ¿Algo más?
La versión específica de las herramientas BeeWare que está utilizando (por ejemplo, Toga 0.5.3). Si estás usando una versión de desarrollo, ¿qué hash de Git estás usando? No basta con decir "la rama principal actual", porque eso puede cambiar a diario.
Las versiones específicas de otros paquetes que deben instalarse para desencadenar el problema. Puedes incluir los resultados de ejecutar python -m pip freeze para proporcionar esta información.
Si se ha generado una bitácora, la bitácora completa.
Si se ha generado un rastreo de pila, el rastreo de pila completo. No proporciones sólo el mensaje de error final: el contexto completo del seguimiento de pila es importante. También es mejor proporcionar esto en formato texto, no como una captura de pantalla.
Cualquier otro aspecto de su equipo o de la configuración de la red que pueda estar influyendo en la incidencia. ¿Es su equipo más antiguo o más lento? ¿Es una máquina de trabajo que puede tener cortafuegos, antivirus u otras restricciones? ¿Tu red es especialmente lenta? ¿Ejecutas tu sistema operativo con una configuración por defecto poco habitual (como una tipografía muy grande o alguna otra tecnología de asistencia activada)?

Trata de pensar con originalidad e incluye todo lo que se te ocurra que pueda influir en el problema que estás experimentando. Si nos das más de lo que necesitamos, es fácil que ignoremos lo que no necesitamos. No se nos ocurrirá nada que hayas omitido.

Un ejemplo mínimo¶

La parte más importante de un informe de fallo es un caso de reproducción mínimo. Debería ser posible para un tercero leer las instrucciones de su caso de reproducción, seguir esas instrucciones y observar el mismo problema. Esto puede significar proporcionar un proyecto de muestra que exhiba el problema o, incluso mejor, utilizar un ejemplo preexistente (como un tutorial o un proyecto de ejemplo que forme parte de la base de código existente).

Tu proyecto completo no es un caso de reproducción mínima. Un caso de reproducción mínimo no contendría ningún código que no sea absolutamente requerido para fabricar un problema. Sé despiadado al componer tu caso de reproducción: si un botón no es necesario para fabricar el problema, no lo incluyas.

Muy a menudo, el proceso de desarrollo de este caso de reproducción mínima revelará el origen del problema, porque el acto de crear el ejemplo mínimo te obliga a averiguar exactamente qué está causando la incidencia, si se trata de un fallo en el código, o se deriva de suposiciones incorrectas o del uso del API.

También sería explícito en las instrucciones de reproducción. Decir «Cierra la aplicación de ejemplo» podría significar pulsar en el botón de cierre de la ventana, seleccionar «salir» en un menú o escribir Ctrl+C en un terminal. Tu informe no dejaría ningún lugar para la ambigüedad en lo que hay que hacer para reproducir el problema.

Envío del informe¶

Navega a la lista de incidencias del proyecto list, pulsa en el botón «Nueva incidencia» y selecciona «Notificación de fallo» para iniciar el proceso.

Debe rellenar todas las secciones de la plantilla de incidencias. Le proporcionamos la plantilla como ayuda para que nos facilite la información necesaria. Recuerde que siempre puede (¡y debe!) facilitar más información que ya requiere la plantilla, pero como mínimo necesitamos toda la información presente en la plantilla.

Cuando incluya código, en caso de que pueda reproducirlo con un ejemplo existente, como el tutorial de BeeWare, puede proporcionar un enlace. De lo contrario, proporcione el código en el informe. Debería tener formato Markdown; un bloque de código necesita tres acentos graves (```) antes y después.

Si necesita incluir un bloque largo de texto largo, puede convertirlo en contenido colapsado utilizando la sintaxis siguiente:

<details>
<summary>Collapsed content title</summary>
Long block of text.
</details>

Una vez que haya proporcionado toda la información posible, pulse en «Crear» para enviar el informe.

Utilice la CLI de GitHub para crear una incidencia

Si se utiliza directamente la CLI de GitHub (gh), se omiten las plantillas que hemos creado. Estas plantillas sirven para garantizar que dispongamos de la información necesaria para gestionar la incidencia.

Si vas a utilizar gh para crear una incidencia nueva, utiliza lo siguiente:

gh issue create --web

Al utilizar --web, se abre el navegador en la página de plantillas de incidencias y te permite crear una incidencia utilizando la plantilla apropiada.