Utilisation des outils¶

L'un des retours d'information les plus précieux que nous puissions obtenir est celui des personnes qui essaient d'utiliser les outils BeeWare et qui découvrent un point de friction ou une fonctionnalité manquante. Il est extrêmement utile pour nous de comprendre les difficultés que vous pouvez rencontrer lorsque vous utilisez les outils à des fins réelles.

Pensez à ce que vous avez toujours voulu construire et essayez de le faire. S'il s'avère que vous êtes en mesure de réaliser votre projet, félicitations ! Vous avez la chose que vous avez toujours voulue.

Toutefois, si vous n'y parvenez pas, faites-nous savoir ce qui n'a pas fonctionné. Y a-t-il une fonctionnalité manquante ? La documentation est-elle confuse ou présente-t-elle des lacunes ? En partageant votre expérience, vous nous donnez un aperçu utile que nous pouvons utiliser pour façonner notre processus de planification.

Si vous rencontrez des problèmes, lancez un nouveau sujet de discussion, car il peut s'agir du début d'un nouveau problème ou d'une proposition de fonctionnalité.

Utilisation des outils de contribution¶

Soumettre un nouveau problème

La rédaction d'un bon rapport de problème ou de bogue peut faire toute la différence dans la capacité à résoudre un problème. Voici comment soumettre un bon rapport de bogue à BeeWare.

Recherche de questions existantes¶

Avant de soumettre un nouveau problème, recherchez dans l'index les problèmes existants qui correspondent au vôtre. S'il existe un problème ouvert qui semble correspondre à votre problème, ajoutez un commentaire à ce problème avec des informations supplémentaires sur votre expérience. Par exemple, si vous rencontrez le problème avec une version différente de Python ou un système d'exploitation différent, ces informations supplémentaires peuvent être utiles pour déterminer l'impact ou la cause d'un problème.

Si vous trouvez un problème fermé qui semble correspondre à votre problème, vérifiez à quand remonte la fermeture de ce problème. Si le problème a été fermé très récemment, cela signifie probablement que votre bogue a été corrigé et qu'il sera corrigé dans la prochaine version. Si le problème a été fermé il y a plus de 4 mois, il est probable que ce que vous rencontrez est un problème différent - même si le message d'erreur semble similaire.

Si vous ne trouvez pas de problème qui corresponde à ce que vous observez, il peut être approprié d'ouvrir un nouveau problème.

Commencer par une discussion¶

Avant de soumettre un problème sur GitHub, envisagez de commencer par une discussion pour demander si ce que vous rencontrez est en fait un bogue, ou un problème avec votre installation ou votre processus. A moins que vous n'observiez un comportement qui contredise directement le comportement documenté, il vaut probablement la peine de poser une question avant de soumettre directement un rapport de bogue. S'il s'avère que vous avez trouvé un problème, un sujet de discussion peut facilement être transformé en problème.

Lancer une discussion peut également vous aider à vous assurer que vous signalez un problème au bon endroit. Même si vous avez rencontré un problème en utilisant BeeWare, le problème peut être causé par un bogue dans un autre projet de l'écosystème BeeWare.

Rédiger un bon rapport de bogue¶

Si un nouveau problème est nécessaire, il est important de fournir autant de détails que possible. Un bon rapport de bogue comprend toutes les informations potentiellement liées au bogue, ainsi que le plus petit exemple de reproduction possible.

L'exemple de reproduction doit être aussi court et concis que possible tout en présentant le bogue. Fournir un exemple massif rend le dépannage beaucoup plus difficile, surtout s'il s'appuie sur d'autres bibliothèques ou s'il nécessite une connaissance approfondie du comportement attendu ou de la logique interne de l'exemple.

Nous avons besoin d'autant de détails que possible. Cela inclut, mais n'est certainement pas limité à :

La version de votre système d'exploitation - jusqu'à la version micro (par exemple, macOS 15.7.2).
Votre version de Python, y compris la version micro (par exemple, 3.14.1).
Comment avez-vous installé Python ? L'avez-vous téléchargé depuis python.org ? Avez-vous utilisé Homebrew ? uv ? pyenv ? conda ? Quelque chose d'autre ?
La version spécifique des outils BeeWare que vous utilisez (par exemple, Toga 0.5.3). Si vous utilisez une version de développement, quel hash Git utilisez-vous ? Il ne suffit pas de dire "la branche principale actuelle", car elle peut changer quotidiennement.
Les versions spécifiques des autres paquets qui doivent être installés pour déclencher le problème. Vous pouvez inclure les résultats de l'exécution de python -m pip freeze pour fournir ces informations.
Si un fichier journal a été généré, le fichier journal complet.
Si une trace de pile a été générée, la entière trace de pile. Ne vous contentez pas de fournir le message d'erreur final - le contexte complet de la trace de pile est important. Il est également préférable de fournir cette information au format texte, pas sous forme de capture d'écran.
Tout autre élément concernant votre ordinateur ou la configuration de votre réseau qui pourrait avoir une incidence sur le problème. Votre ordinateur est-il plus ancien ou plus lent ? S'agit-il d'un ordinateur professionnel qui peut être équipé de pare-feu, de contrôleurs de virus ou d'autres restrictions ? Votre réseau est-il particulièrement lent ? Votre système d'exploitation fonctionne-t-il avec des paramètres par défaut inhabituels (par exemple, une police de caractères très grande ou une autre technologie d'assistance activée) ?

Essayez de sortir des sentiers battus et d'inclure tout ce à quoi vous pouvez penser et qui pourrait avoir un impact sur le problème que vous rencontrez. Si vous nous donnez plus que ce dont nous avons besoin, nous pouvons facilement ignorer ce dont nous n'avons pas besoin. Nous ne pouvons pas trouver quelque chose que vous avez oublié.

Un exemple minimal¶

La partie la plus importante d'un rapport de bogue est un cas de reproduction minimal. Il doit être possible pour un tiers de lire les instructions relatives à votre cas de reproduction, de suivre ces instructions et d'observer le même problème. Cela peut signifier qu'il faut fournir un exemple de projet qui présente le problème ou, mieux encore, utiliser un exemple préexistant (tel qu'un tutoriel ou un projet d'exemple qui fait partie de la base de code existante).

Votre projet complet n'est pas un cas de reproduction minimal. Un cas de reproduction minimal ne doit contenir aucun code qui ne soit pas absolument nécessaire à la résolution d'un problème. Soyez impitoyable dans la composition de votre cas de reproduction - si un bouton n'est pas nécessaire pour résoudre le problème, n'incluez pas ce bouton.

Très souvent, le processus de développement de ce cas de reproduction minimal révèle la source du problème, car la création de l'exemple minimal vous oblige à déterminer exactement ce qui cause le problème, qu'il s'agisse d'un bogue dans le code ou d'une hypothèse ou d'une utilisation incorrecte de l'API.

Vous devez également être explicite dans les instructions de reproduction. Dire "Fermer l'application exemple" peut signifier cliquer sur le bouton de fermeture de la fenêtre, sélectionner "quitter" dans un menu ou taper Control-C dans un terminal. Votre rapport ne doit laisser aucune place à l'ambiguïté quant à ce qu'il faut faire pour reproduire le problème.

Soumission du rapport¶

Accédez à la liste des problèmes du projet, cliquez sur le bouton « Nouveau problème » et sélectionnez « Rapport de bogue » pour lancer le processus.

Vous devez remplir toutes les sections du modèle de question ** Nous fournissons le modèle pour vous aider à fournir les informations nécessaires. N'oubliez pas que vous pouvez (et devez !) toujours fournir plus d'informations que le modèle ne l'exige, mais nous avons besoin au minimum de toutes les informations présentes dans le modèle.

Lorsque vous incluez du code, si vous pouvez le reproduire avec un exemple existant, tel que le tutoriel de BeeWare, vous pouvez fournir un lien. Sinon, fournissez le code dans le rapport. Il doit être formaté en Markdown ; un bloc de code doit être précédé et suivi de trois crochets (```).

Si vous devez inclure un long bloc de texte, vous pouvez en faire un contenu groupé en utilisant la syntaxe suivante :

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

Une fois que vous avez fourni autant d'informations que possible, cliquez sur "Créer" pour soumettre le rapport.

Proposer une nouvelle fonctionnalité

Vous avez une idée d'amélioration pour BeeWare - comment soumettre cette idée pour examen ?

Faites vos recherches¶

La première étape consiste à rechercher dans l'issue tracker BeeWare les [feature issues (issues tagged "enhancement")] existants (https://github.com/search ?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Aenhancement&type=issues), documentation issues (issues tagged "documentation"), ou Discussion threads pour voir si l'idée a déjà été suggérée. Si c'est le cas, et que vous avez un nouveau contexte ou de nouvelles idées à ajouter, incluez-les dans le fil de discussion existant. Si vous souhaitez obtenir de l'aide pour vos recherches, vous pouvez le demander dans le canal #dev sur le BeeWare Discord. Nous pourrons peut-être vous indiquer des fils de discussion existants, vous fournir un contexte dont vous n'avez peut-être pas conscience, ou relier votre idée à une autre idée qui ne semble pas immédiatement liée.

Discuter de l'idée¶

Si vous ne trouvez aucune référence existante à votre idée, démarrez un [fil de discussion] (https://github.com/beeware/beeware/discussions). Fournissez une description de haut niveau de l'objectif et du cas d'utilisation de votre idée. Incluez toutes les idées que vous avez sur ce à quoi la fonctionnalité ressemblerait, si elle était mise en œuvre, comme la forme générale d'une API, l'aspect visuel d'une capacité, ou le document qui serait ajouté. Le cas échéant, vous devez également inclure toute recherche que vous avez effectuée sur la façon dont votre idée se manifesterait sur différentes plates-formes.

Une fois le fil de discussion ouvert, l'équipe de BeeWare et le reste de la communauté y répondront. L'équipe centrale s'efforcera de fournir au moins une première impression de votre idée dans un délai de deux jours ouvrables. Si une idée est particulièrement complexe, une analyse plus détaillée peut prendre jusqu'à une semaine. Des événements tels que des vacances ou des conférences peuvent allonger légèrement ces délais.

C'est l'occasion pour vous de participer à une conversation sur votre idée. Il se peut que nous vous demandions plus de détails ou de contexte. D'autres membres de la communauté peuvent également participer à la discussion, en apportant d'autres points de vue, des suggestions ou des contre-propositions. Le résultat de cette discussion déterminera les prochaines étapes.

Il est important de comprendre que toutes les idées ne seront pas acceptées. La raison pour laquelle ce processus commence par une proposition est d'éviter que vous ne fassiez tout le travail pour découvrir ensuite qu'il y a une raison pour que votre changement ne soit pas accepté.

Cela ne signifie pas que ce n'était pas une bonne idée ! Il peut y avoir des raisons techniques pour lesquelles elle ne peut pas être mise en œuvre. Par exemple, nous pourrions rejeter une idée dans les cas suivants

Il serait difficile ou impossible de la mettre en œuvre de manière fiable sur toutes les plates-formes prises en charge ; ou
Il serait difficile à entretenir, ou l'entretien nécessiterait l'accès à une technologie ou à un logiciel qui n'est pas largement disponible ; ou
Il sert un public de niche, mais impose des frais généraux importants aux autres utilisateurs.

Si nous déterminons que votre idée ne convient pas, cela ne signifie pas nécessairement que vous devez l'abandonner. Bien que nous puissions rejeter une idée spécifique, nous pourrions être beaucoup plus enclins à ajouter une interface de plugin ou un autre point d'extension qui vous permettrait de maintenir la même fonctionnalité en tant que bibliothèque externe. De cette façon, vous pouvez avoir la fonctionnalité, mais sans que les problèmes spécifiques de maintenance ou les limitations de la fonctionnalité ne deviennent une contrainte pour le projet lui-même.

Transformer en demande formelle de fonctionnalité¶

Une fois que la discussion a abouti à un consensus sur la forme d'une fonctionnalité, vous pouvez créer un nouveau [numéro de demande de fonctionnalité] (https://github.com/beeware/beeware/issues/new/choose), dans le gestionnaire de problèmes BeeWare, qui résume la discussion, avec un lien vers la discussion pour le contexte.

Vous n'êtes pas obligé d'implémenter vous-même votre proposition de fonctionnalité ; vous pouvez ouvrir un problème avec les détails de ce que vous proposez. Cependant, le simple fait de poster un problème ne signifie pas qu'il sera mis en œuvre pour vous. Vous devrez attendre qu'elle soit éventuellement reprise par quelqu'un d'autre intéressé par la même fonctionnalité, qu'il s'agisse d'un autre membre de la communauté ou de l'équipe principale ; cependant, cela n'est pas garanti. Si vous voulez la garantie d'implémentation, vous devrez l'implémenter vous-même, ou payer quelqu'un d'autre pour le faire à votre place.