Uso de las herramientas

Uno de los comentarios más valiosos que podemos recibir es el de las personas que intentan utilizar las herramientas de BeeWare y descubren que hay un punto de fricción o una función que falta. Para nosotros es muy útil conocer las dificultades que pueden surgir al utilizar las herramientas en el mundo real.

Piensa en lo que siempre has querido construir e intenta hacerlo. Si resulta que eres capaz de construir tu proyecto, ¡enhorabuena! Ya tienes lo que siempre quisiste.

Sin embargo, si no lo consigue, díganos qué ha fallado. ¿Falta alguna función? ¿La documentación es confusa o carece de algún aspecto? Compartir su experiencia nos aporta información útil que podemos utilizar para dar forma a nuestro proceso de planificación.

Si experimenta algún problema, inicie un nuevo tema de debate, ya que puede ser el comienzo de una nueva incidencia o propuesta de característica.

Uso de herramientas de contribución

Enviar una nueva incidencia

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.

Proponer una función nueva

Por tanto ya tienes una idea sobre una mejora para BeeWare: ¿cómo presentar esa idea a que sea para consideración?

Haz tu investigación

El primer paso es buscar el seguimiento de la incidencia BeeWare para la prestación de incidencias (incidencias etiquetadas "enhancement"), incidencias de documentación (incidencias etiquetadas "documentation"), o Hilos de discusión para ver si ka idea ha sido sugerida antes. Si tiene, y tiene contexto o ideas nuevas o para añadir, inclúyelas en el hilo existente. Si le gustaría asistir con su investigación, puede solicitar en el canal #dev en el Discord de BeeWare. Es posible que podamos orientarte hacia hilos de conversación existentes, proporcionarte un contexto que quizás desconozcas o conectar tu idea con otra que, a primera vista, no parezca estar relacionada.

Debatir la idea

Si no encuentra ninguna referencia a su idea, inicie un Hilo de debate. Describa a grandes rasgos la finalidad y el caso de uso de su idea. Incluya cualquier idea que tendría sobre como aparecería la prestación, si se implementara, tal como la forma general de un API, el aspecto visual de una capacidad o el documento que se añadiría. Si es aplicable, también incluiría cualquier investigación que hayas realizado sobre como se manifestaría tu idea en plataformas diferentes.

Una vez abierto el hilo de debate, el equipo de BeeWare y el resto de la comunidad responderán. El equipo central intentará ofrecer al menos una primera impresión de su idea en un plazo de dos días laborables. Si una idea es especialmente compleja, un análisis más detallado puede llevar hasta una semana. Acontecimientos como vacaciones y conferencias pueden alargar ligeramente estos plazos.

Esta es su oportunidad de participar en una conversación sobre su idea. Podemos pedirle más detalles o contexto. Otros miembros de la comunidad también pueden participar en el debate, aportando otras perspectivas, sugerencias o contra‐propuestas. El resultado de este debate determinará los siguientes pasos.

Es importante entender que no serán aceptadas todas las ideas. La razón por la que este proceso comienza con una propuesta es para evitar que hagas todo el trabajo y luego descubras que hay una razón por la que su cambio no será aceptado.

Esto no significa que no fuera una buena idea. Puede haber razones técnicas por las que no pueda llevarse a cabo. Por ejemplo, podríamos rechazar una idea si:

• Sería difícil o imposible implementar de forma fiable a través de todas las plataformas admitidas; o
• Sería difícil de mantener, o su mantenimiento requeriría acceder a tecnología o software que no estén ampliamente disponibles; o
• Sirve a un nicho público, pero impone una sobrecarga significativa a otros usuarios.

Si determinamos que tu idea no encaja, no significa necesariamente que debas renunciarla. Si bien podemos rechazar una idea específica, podemos estar mucho más dispuestos a añadir una interfaz de plugin u otro punto de extensión que le permita mantener la misma prestación como una biblioteca externa. De este modo, podrá disponer de la prestación, pero sin que los problemas específicos de mantenimiento o las limitaciones de la prestación se conviertan en una restricción para el propio proyecto.

Convertir en una requerimiento formal de prestación

Una vez que la discusión ha llegado a un consenso sobre la forma de una prestación, puede crear una nueva prestación solicitada de incidencia, en la incidencia del seguimiento BeeWare, que resuma la discusión, enlazando a la discusión para el contexto.

No tienes por qué implementar tú mismo tu propuesta de prestación; puedes abrir una incidencia con los detalles de lo que propones. Sin embargo, el mero hecho de publicar la incidencia no significa que vaya a implementarse. Tendrás que esperar a que otra persona interesada en la misma prestación, ya sea otro miembro de la comunidad o el equipo central, la recoja; sin embargo, no está garantizado que esto suceda. Si quieres la implementación garantizada, tendrás que implementarla tú mismo, o pagar a alguien para que lo haga por ti.