Enviar un nuevo problema¶

Redactar un buen informe de incidencia o error puede marcar la diferencia a la hora de solucionar un problema. A continuación se explica cómo enviar un buen informe de error a BeeWare.

Búsqueda de temas existentes¶

Antes de enviar una nueva incidencia, 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ó. Si se cerró hace muy poco, es probable que el error 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, podría ser conveniente abrir una nueva incidencia.

Empezar con un debate¶

Antes de enviar un problema a GitHub, considera la posibilidad de comenzar con una discusión para preguntar si lo que estás experimentando es realmente un error, o un problema 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 un problema, 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 un problema en el lugar más adecuado. Aunque hayas experimentado un problema al utilizar BeeWare, el problema podría estar causado por un error en un proyecto diferente del ecosistema BeeWare.

Redactar un buen informe de error¶

Si se requiere una nueva incidencia, 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 sin dejar de mostrar el fallo. Proporcionar un ejemplo masivo dificulta significativamente la resolución de problemas, especialmente si depende de otras bibliotecas o requiere un amplio conocimiento del comportamiento esperado o de la lógica interna del ejemplo.

Necesitamos todos los detalles posibles. Esto incluye, pero definitivamente no se limita a:

La versión de tu sistema operativo, hasta la microversión (por ejemplo, macOS 15.7.2).
Tu versión de Python, también hasta la versión micro (por ejemplo, 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 puede cambiar a diario.
Las versiones específicas de otros paquetes que deben instalarse para desencadenar el problema. Puede incluir los resultados de ejecutar python -m pip freeze para proporcionar esta información.
Si se ha generado un archivo de registro, el archivo de registro entero.
Si se ha generado un stacktrace, el stacktrace entero. No proporciones sólo el mensaje de error final - el contexto completo del stacktrace es importante. También es mejor proporcionar esto en formato texto, no como una captura de pantalla.
Cualquier otro aspecto de su ordenador o de la configuración de la red que pueda estar influyendo en el problema. ¿Es su ordenador más antiguo o más lento? ¿Es una máquina de trabajo que puede tener cortafuegos, antivirus u otras restricciones? ¿Su red es especialmente lenta? ¿Ejecutas tu sistema operativo con una configuración por defecto poco habitual (como una fuente 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 tienes. 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 ejemplo que muestre 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 debe contener ningún código que no sea absolutamente necesario 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 el problema, si se trata de un error en el código, o se deriva de suposiciones incorrectas o del uso de la API.

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

Presentación del informe¶

Navigate to the project issues list, click the "New issue" button, and choose "Bug report" to begin the process.

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 de la que 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. Debe tener formato Markdown; un bloque de código necesita tres puntos suspensivos (```) antes y después.

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

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

Una vez que haya proporcionado toda la información posible, haga clic en "Crear" para enviar el informe.