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 cuestión o propuesta de función.

Uso de herramientas de contribución¶

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.

Proponer una nueva función

Así que tienes una idea sobre una mejora para BeeWare - ¿cómo presentar esa idea para su consideración?

Investigue¶

El primer paso es buscar en el gestor de incidencias BeeWare los [feature issues (issues tagged "enhancement")] existentes (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Aenhancement&type=issues), problemas de documentación (problemas etiquetados como "documentación"), o Hilos de discusión para ver si la idea ya se ha sugerido antes. Si es así, y usted tiene un nuevo contexto o ideas que añadir, inclúyalas en el hilo existente. Si necesitas ayuda con tu investigación, puedes preguntar en el canal #dev del BeeWare Discord. Es posible que podamos indicarte hilos ya existentes, proporcionarte un contexto que quizá no conozcas o relacionar tu idea con otra que no parezca inmediatamente 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 tenga sobre el aspecto que tendría la función, si se implementara, como la forma general de una API, el aspecto visual de una capacidad o el documento que se añadiría. Si procede, también debes incluir cualquier investigación que hayas realizado sobre cómo se manifestaría tu idea en diferentes plataformas.

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 contrapropuestas. El resultado de este debate determinará los siguientes pasos.

Es importante entender que no todas las ideas serán aceptadas. La razón por la que este proceso comienza con una propuesta es para evitar que usted haga todo el trabajo y luego descubra 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 aplicarlo de forma fiable en todas las plataformas compatibles.
Sería difícil de mantener, o su mantenimiento requeriría el acceso a tecnología o programas informáticos que no están ampliamente disponibles; o
Sirve a un público nicho, pero impone una sobrecarga significativa a otros usuarios.

Si determinamos que tu idea no encaja, no significa necesariamente que debas renunciar a ella. 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 característica como una biblioteca externa. De este modo, podrá disponer de la función, pero sin que los problemas específicos de mantenimiento o las limitaciones de la función se conviertan en una restricción para el propio proyecto.

Convertir en una solicitud formal¶

Una vez que la discusión ha llegado a un consenso sobre la forma de una característica, puede crear una nueva feature request issue, en el issue tracker BeeWare, que resuma la discusión, enlazando a la discusión para el contexto.

No tienes por qué implementar tú mismo tu propuesta de funcionalidad; 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 función, ya sea otro miembro de la comunidad o el equipo central, la recoja; sin embargo, no está garantizado que esto ocurra. Si quieres la implementación garantizada, tendrás que implementarla tú mismo, o pagar a alguien para que lo haga por ti.