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.