Résolution d'un problème¶

BeeWare suit une liste de [problèmes connus] (https://github.com/search?q=org%3Abeeware%20is%3Aopen%20is%3Aissue%20label%3Abug&type=issues). Tous ces problèmes sont des candidats sur lesquels il faut travailler.

Cette liste peut être filtrée de différentes manières. Par exemple, vous pouvez filtrer par plate-forme, afin de vous concentrer sur les problèmes qui affectent les plates-formes sur lesquelles vous pouvez tester ; ou vous pouvez filtrer par type de problème, comme documentation bugs. Il existe également un filtre pour les [bons premiers numéros] (https://github.com/search?q=org%3Abeeware+is%3Aopen+is%3Aissue+label%3Abug+label%3A%22good+first+issue%22&type=issues) - il s'agit de problèmes qui ont été identifiés comme ayant une cause connue, et nous pensons que la correction devrait être relativement simple (bien que nous puissions nous tromper dans notre analyse).

Si un problème date de plus de 6 mois, il est tout à fait possible qu'il ait été résolu. La première étape consiste donc à vérifier que vous pouvez reproduire le problème. Utilisez les informations fournies dans le rapport de bogue pour essayer de reproduire le problème. Si vous ne pouvez pas reproduire le problème, indiquez ce que vous avez trouvé dans un commentaire sur le problème et choisissez un autre problème.

Si vous pouvez reproduire le problème, essayez de le résoudre ! Déterminez quelle combinaison de code met en œuvre la fonctionnalité et voyez si vous pouvez trouver ce qui ne fonctionne pas correctement.

Même si vous ne pouvez pas résoudre le problème, il est utile de signaler tout ce que vous avez découvert au cours du processus en tant que commentaire sur le problème. Si vous pouvez trouver la source du problème, mais pas la solution, cette connaissance sera souvent suffisante pour que quelqu'un qui en sait plus sur une plateforme puisse résoudre le problème. Si le problème ne fournit pas déjà un bon cas de reproduction (un petit exemple d'application qui ne fait rien d'autre que reproduire le problème), en fournir un peut être d'une grande aide.

Contribuer à la résolution d'un problème¶

Configurer un environnement de développement

Contribuer à BeeWare nécessite la mise en place d'un environnement de développement.

Conditions préalables¶

Vous devrez installer les prérequis suivants.

macOSLinuxWindows

BeeWare nécessite Python 3.10+. Vous aurez également besoin d'une méthode pour gérer les environnements virtuels (comme venv).

Vous pouvez vérifier la version de Python que vous avez installée en exécutant :

Python 3.8.10 (version par défaut, 20 juillet 2020, 16 h 16)

Si plusieurs versions de Python sont installées, vous devrez peut-être remplacer python3 par un numéro de version spécifique (par exemple, python{{ récent_python_version }}).

Nous recommandons d'éviter les versions de Python récemment publiées (c'est-à-dire les versions qui ont un numéro de micro-version ".0" ou ".1", comme par exemple, 3.14.0). En effet, les outils nécessaires au support de Python sur macOS ne sont généralement pas disponibles pour les versions stables de Python récemment publiées.

BeeWare nécessite Python 3.10+. Vous aurez également besoin d'une méthode pour gérer les environnements virtuels (comme venv).

Vous pouvez vérifier la version de Python que vous avez installée en exécutant :

Python 3.8.10 (version par défaut, 20 juillet 2020, 16 h 16)

Si plusieurs versions de Python sont installées, vous devrez peut-être remplacer python3 par un numéro de version spécifique (par exemple, python{{ récent_python_version }}).

Nous recommandons d'éviter les versions de Python récemment publiées (c'est-à-dire les versions qui ont un numéro de micro-version ".0" ou ".1", comme par exemple, 3.14.0). En effet, les outils nécessaires au support de Python sur Linux ne sont généralement pas disponibles pour les versions stables de Python récemment publiées.

BeeWare nécessite Python 3.10+. Vous aurez également besoin d'une méthode pour gérer les environnements virtuels (comme venv).

Vous pouvez vérifier la version de Python que vous avez installée en exécutant :

C:\...>py -3 --version

Si plusieurs versions de Python sont installées, vous devrez peut-être remplacer le -3 par un numéro de version spécifique (par exemple, -python{{ récent_python_version }}).

Nous recommandons d'éviter les versions de Python récemment publiées (c'est-à-dire les versions qui ont un numéro de micro-version ".0" ou ".1", comme par exemple, 3.14.0). En effet, les outils nécessaires au support de Python sur Windows ne sont généralement pas disponibles pour les versions stables de Python récemment publiées.

Configurez votre environnement de développement¶

La méthode recommandée pour mettre en place votre environnement de développement pour BeeWare est d'utiliser un environnement virtuel, puis d'installer la version de développement de BeeWare et ses dépendances.

Cloner le dépôt BeeWare.¶

Ensuite, allez sur la page BeeWare sur GitHub, et, si vous ne l'avez pas déjà fait, forker le dépôt dans votre propre compte. Cliquez ensuite sur le bouton "<> Code" de votre fork. Si l'application GitHub desktop est installée sur votre ordinateur, vous pouvez sélectionner "Open with GitHub Desktop" ; sinon, copiez l'URL HTTPS fournie et utilisez-la pour cloner le dépôt sur votre ordinateur à l'aide de la ligne de commande :

macOSLinuxWindows

Créer un dépôt BeeWare, et ensuite :

$ git clone https://github.com/<votre nom d'utilisateur>/beeware.git

(en remplaçant votre nom d'utilisateur GitHub)

Créer un dépôt BeeWare, et ensuite :

$ git clone https://github.com/<votre nom d'utilisateur>/beeware.git

(en remplaçant votre nom d'utilisateur GitHub)

Créer un dépôt BeeWare, et ensuite :

C:\...>git clone https://github.com/<votre nom d'utilisateur>/beeware.git

(en remplaçant votre nom d'utilisateur GitHub)

Définir un référentiel en amont¶

Après avoir cloné votre fork, ajoutez le dépôt BeeWare en tant que upstream distant. Cela permet à votre clone local de disposer d'une référence au dépôt d'origine, ce qui facilite la synchronisation des mises à jour au fil du temps.

Vous aurez également besoin des balises de upstream afin que des outils tels que Toga et Briefcase puissent déterminer les numéros de version exacts :

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Si vous souhaitez que votre fourche inclue également ces balises, vous pouvez les pousser :

$ git push --tags

Cela peut être utile si vous créez un nouveau clone ultérieurement et que vous souhaitez que les balises soient disponibles à partir de votre fork.

Créer un environnement virtuel¶

Pour mettre en place un environnement virtuel et mettre à jour pip, exécutez :

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Votre prompt devrait maintenant être précédé du préfixe (.venv).

Installer BeeWare¶

Maintenant que vous avez le code source, vous pouvez faire une editable install de BeeWare dans votre environnement de développement. Exécutez la commande suivante :

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Activer la pré-commission¶

BeeWare utilise un outil appelé pre-commit pour identifier les problèmes simples et standardiser le formatage du code. Pour ce faire, il installe un hook git qui exécute automatiquement une série de linters de code avant de finaliser tout commit git. Pour activer pre-commit, exécutez :

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Vous êtes maintenant prêt à pirater BeeWare !

Travailler à partir d'une succursale

Avant de commencer à travailler sur votre changement, assurez-vous d'avoir créé une branche. Par défaut, lorsque vous clonez la fourche de votre dépôt, vous serez extrait sur la branche main. C'est une copie directe de la branche main de BeeWare.

Bien que vous puissiez soumettre une demande d'extraction à partir de votre branche main, il est préférable que vous ne fassiez pas cela. Si vous soumettez une demande d'extraction qui est presque correcte, le membre de l'équipe principale qui examine votre demande d'extraction peut être en mesure de faire les changements nécessaires, plutôt que de donner un feedback demandant un changement mineur. Cependant, si vous soumettez votre demande d'extraction depuis votre branche main, les réviseurs ne peuvent pas faire de modifications.

Travailler à partir de votre branche principale rend également les choses plus difficiles pour vous une fois que vous avez terminé votre première demande d'extraction. Si vous voulez travailler sur une seconde demande, vous aurez besoin d'une copie "propre" de la branche principale du projet en amont sur laquelle baser votre seconde contribution ; si vous avez fait votre première contribution à partir de votre branche main, vous n'avez plus cette version propre disponible.

Au lieu de cela, vous devez effectuer vos modifications sur une branche de fonctionnalité. Une branche de fonctionnalité a un nom simple pour identifier le changement que vous avez fait. Par exemple, si vous corrigez un bogue qui cause des problèmes de compilation sur Windows 11, vous pourriez créer une branche de fonctionnalité fix-win11-build. Si votre bogue est lié à un problème spécifique qui a été rapporté, il est également courant de faire référence au numéro de ce problème dans le nom de la branche (par exemple, fix-1234).

Pour créer une branche fix-win11-build, exécutez :

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Reproduire le problème

On ne peut pas résoudre un problème si l'on n'a pas le problème en premier lieu. Par conséquent, la reproduction du problème est une condition préalable à sa résolution. Dans le domaine des logiciels, les problèmes sont communément appelés "bogues", et les questions sont souvent appelées "rapports de bogues".

Quelqu'un a fourni un rapport de bogue. Vous devez vous assurer que les étapes décrites par le rapporteur aboutissent au bogue signalé. Pouvez-vous reproduire le même résultat en faisant exactement ce qui est décrit dans le rapport ? Si ce n'est pas le cas, vous devez comprendre pourquoi.

Bugs dans le code¶

Dans une situation idéale, vous aurez la même configuration que la personne qui a signalé le bogue, vous suivrez les étapes et vous serez en mesure de reproduire le bogue tel qu'il est décrit. Dans de nombreux cas, cependant, ce ne sera pas aussi simple. De nombreux rapports de bogues ne contiennent que de vagues explications et un vague ensemble de conditions. Le problème est que de nombreux bogues varient en fonction de l'ensemble des conditions impliquées, y compris la manière dont ils sont utilisés, diverses conditions préalables, le système d'exploitation, la version du système d'exploitation, l'architecture du processeur ou le fait que la machine de l'utilisateur soit ancienne et lente ou nouvelle et rapide. Plus nous disposons d'informations sur la situation entourant le bogue, mieux c'est. Essayez de reproduire l'ensemble des conditions fournies par le rapporteur. Si vous n'y parvenez pas, la prochaine étape consistera peut-être à demander plus d'informations à la personne qui a signalé le bogue.

La meilleure façon de reproduire un bogue est d'utiliser le plus petit exemple possible qui présente encore le problème. La plupart du temps, les rapporteurs ne fourniront pas d'exemple minimum viable ; s'ils fournissent un exemple, il sera copié directement à partir de leur application "réelle". Votre objectif est de réduire le rapport à la forme la plus simple possible qui présente le problème. Le meilleur cas de reproduction est le plus petit programme possible. Cette réduction est elle-même utile car elle permet de déterminer quel est le problème réel. N'importe qui peut prendre l'exemple minimal, l'exécuter et observer le bogue décrit.

Bugs dans la documentation¶

Les bogues dans la documentation peuvent se manifester de différentes manières. Il y a des problèmes de formatage qui entraînent des problèmes de rendu. Parfois, il ne s'agit même pas d'un bogue ; la personne peut avoir mal lu la documentation ou avoir commis une véritable erreur. Cela ne signifie pas nécessairement qu'il n'y a pas de problème avec la documentation. Le contenu peut être peu clair ou imprécis, laissant place à la confusion ou à une mauvaise interprétation. Il est possible qu'un concept qui devrait être discuté ne le soit pas, parce qu'il n'est pas du tout documenté.

Lorsqu'un bogue est signalé pour un problème de documentation, vous devez vérifier que le problème signalé existe toujours. Dans le cas des problèmes de rendu, vous devrez construire la documentation pour voir si vous pouvez reproduire le problème. Pour les problèmes de contenu, il suffit de vérifier que personne n'a soumis de mise à jour.

Mise à jour de la question¶

La dernière étape du processus de triage consiste à documenter vos conclusions en laissant un commentaire sur le problème.

Si vous êtes en mesure de reproduire le problème exactement comme il est décrit, c'est tout ce que vous avez à dire. Laissez un commentaire indiquant que vous avez confirmé que vous rencontrez le même problème, de la manière exacte décrite par le rapporteur original.

Si vous êtes en mesure de fournir un contexte supplémentaire, donnez-en les détails. Il peut s'agir de la possibilité de reproduire le problème sur un système d'exploitation différent, ou avec une version différente de certains des logiciels concernés, ou tout autre élément différent du rapport original.

Si le rapport original ne contient pas les détails dont vous avez besoin pour reproduire le rapport, incluez ces détails. Il peut s'agir de fournir des détails sur le système d'exploitation ou la version que le rapport original ne mentionnait pas, des journaux plus complets ou des traces de pile, ou des instructions plus claires sur la séquence exacte des opérations nécessaires pour reproduire le problème. Si vous avez développé une méthode plus simple pour reproduire le problème (ou si le rapport original n'a pas fourni de cas de reproduction), vous pouvez inclure les détails de cette méthodologie de reproduction.

Si vous ne parvenez pas à reproduire le problème, laissez également un commentaire détaillant ce que vous avez essayé. Savoir où un problème n'existe pas est presque aussi important que savoir où il existe, car cela permet de réduire les causes possibles. Si vous avez des hypothèses sur les raisons pour lesquelles vous ne parvenez pas à reproduire le problème (par exemple, si vous pensez qu'il s'agit d'une erreur d'utilisation ou que le problème a été résolu par une récente mise à jour du système d'exploitation), incluez ces spéculations dans votre commentaire.

Enfin, vous pouvez faire part de vos recommandations à l'équipe centrale. Si vous pensez que le rapport original est erroné, suggérez que le problème soit clos ; si vous avez une théorie sur la cause du problème, vous pouvez également la suggérer. Vos commentaires aideront l'équipe centrale à déterminer comment faire passer le problème à l'étape suivante.

Si la résolution du problème nécessite des modifications du code:

Écrire, exécuter et tester du code

Pour corriger un bug ou ajouter une fonctionnalité, vous devrez écrire du nouveau code.

Nous disposons d'un guide de style de codage qui présente nos directives pour l'écriture de code pour BeeWare.

Développement piloté par les tests¶

Un bon moyen de s'assurer que votre code fonctionnera comme prévu consiste à rédiger d'abord un scénario de test pour le vérifier. Ce scénario de test devrait initialement échouer, car le code qu'il est censé tester n'existe pas encore. Vous pouvez ensuite apporter les modifications nécessaires au code pour que le test réussisse, et ainsi avoir la certitude que ce que vous avez écrit résout bien le problème que vous souhaitiez résoudre.

Exécutez votre code¶

Une fois votre code écrit, vous devez vous assurer qu'il fonctionne. Vous devrez l'exécuter manuellement pour vérifier qu'il se comporte comme prévu. Si ce n'est pas déjà fait, il est conseillé de rédiger un scénario de test pour vos modifications ; comme indiqué plus haut, ce test devrait échouer si votre code est commenté ou s'il n'est pas présent.

Vous allez ajouter votre scénario de test à la suite de tests afin qu'il puisse être exécuté en même temps que les autres tests. L'étape suivante consiste à exécuter la suite de tests.

Exécution des tests et de la couverture¶

BeeWare utilise tox pour gérer le processus de test et pytest pour sa propre suite de tests.

La commande par défaut tox comprend l'exécution de :

hooks de pré-commit
Vérification des notes de mise à jour
vérification syntaxique de la documentation
suite de tests pour les versions disponibles de Python
rapports sur la couverture de code

C'est en substance ce que CI exécute lorsque vous soumettez une pull request.

Pour exécuter l'ensemble complet des tests, tapez :

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

L'exécution de la suite de tests complète peut prendre un certain temps. Vous pouvez l'accélérer considérablement en exécutant tox en parallèle, en lançant tox p (ou tox run-parallel). Lorsque vous exécutez la suite de tests en parallèle, vous recevrez moins d'informations sur l'avancement de l'exécution, mais vous obtiendrez tout de même un résumé des problèmes détectés à la fin de la session de tests. Vous devriez voir s'afficher un message indiquant que les tests ont été exécutés. Vous verrez peut-être des tests SKIPPED, mais vous ne devriez jamais obtenir de résultats de test FAIL ou ERROR. Nous exécutons notre suite de tests complète avant de fusionner chaque correctif. Si ce processus détecte des problèmes, nous ne fusionnons pas le correctif. Si vous constatez une erreur ou un échec de test, soit il y a quelque chose d'anormal dans votre environnement de test, soit vous avez trouvé un cas limite que nous n'avons jamais rencontré auparavant — dans tous les cas, faites-le-nous savoir !

Outre la réussite des tests, cela devrait indiquer une couverture de test de 100 %.

Exécution de variantes de test¶

Exécuter des tests pour plusieurs versions de Python¶

Par défaut, de nombreuses commandes tox tenteront d'exécuter la suite de tests plusieurs fois, une fois pour chaque version de Python prise en charge par BeeWare. Pour cela, chacune de ces versions de Python doit toutefois être installée sur votre machine et accessible au processus de [détection]tox de Python de (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). En général, si une version de Python est disponible via PATH, alors tox devrait pouvoir la détecter et l'utiliser.

Exécuter uniquement la suite de tests¶

Si vous effectuez des itérations rapides sur une nouvelle fonctionnalité, vous n'avez pas besoin d'exécuter l'ensemble complet des tests ; vous pouvez exécuter uniquement les tests unitaires. Pour ce faire, exécutez la commande suivante :

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Exécuter un sous-ensemble de tests¶

Par défaut, tox exécute tous les tests de la suite de tests unitaires. Lorsque vous développez un nouveau test, il peut être utile de n'exécuter que ce test-là. Pour ce faire, vous pouvez passer n'importe quel spécificateur pytest en argument à tox. Ces chemins d'accès aux tests sont relatifs au répertoire briefcase. Par exemple, pour n'exécuter que les tests contenus dans un seul fichier, tapez :

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Vous obtiendrez tout de même un rapport de couverture lorsque vous exécuterez une partie de la suite de tests, mais les résultats de couverture ne porteront que sur les lignes de code qui ont été exécutées par les tests spécifiques que vous avez lancés.

Exécuter la suite de tests pour une version spécifique de Python¶

Par défaut, tox -e py s'exécutera en utilisant l'interpréteur associé à python sur votre machine. Si plusieurs versions de Python sont installées et que vous souhaitez tester une version spécifique parmi celles-ci, vous pouvez indiquer la version de Python à utiliser. Par exemple, pour exécuter la suite de tests avec Python 3.10, tapez :

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Il est possible d'exécuter un sous-ensemble de tests en ajoutant -- et une spécification de test à la ligne de commande.

Exécuter la suite de tests sans couverture (rapidement)¶

Par défaut, tox exécute la suite de tests pytest en mode mono-thread. Vous pouvez accélérer l'exécution de la suite de tests en la lançant en parallèle. Ce mode ne génère pas de fichiers de couverture en raison de la complexité liée à la capture de la couverture au sein des processus lancés. Pour exécuter une seule version de Python en mode « rapide », tapez :

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Il est possible d'exécuter un sous-ensemble de tests en ajoutant -- et une spécification de test à la ligne de commande ; il est possible d'utiliser une version spécifique de Python en ajoutant la version à la cible de test (par exemple, py310-fast pour exécuter fast sur Python 3.10).

Couverture du code¶

BeeWare assure une couverture de 100 % de son code source. Lorsque vous ajoutez ou modifiez du code dans le projet, vous devez ajouter du code de test afin de garantir la couverture de toutes les modifications apportées.

Cependant, BeeWare cible plusieurs plateformes ainsi que plusieurs versions de Python ; il n'est donc pas possible de vérifier la couverture complète sur une seule plateforme et une seule version de Python. Pour pallier cela, plusieurs règles de couverture conditionnelles sont définies dans la section tool.coverage.coverage_conditional_plugin.rules de pyproject.toml (par exemple, no-cover-if-is-windows peut être utilisé pour marquer un bloc de code qui ne sera pas exécuté lors de l'exécution de la suite de tests sous Windows). Ces règles servent à identifier les sections de code qui ne sont couvertes que sur certaines plateformes ou versions de Python.

Il convient de noter que la génération de rapports de couverture peut présenter quelques particularités selon la version de Python utilisée. Par exemple, si les fichiers de couverture sont générés avec une version de Python mais que le rapport est établi avec une autre, celui-ci peut contenir des faux positifs concernant des branches non couvertes. C'est pourquoi il est recommandé de toujours utiliser, pour la génération du rapport, la version de Python la plus ancienne ayant servi à créer les fichiers de couverture.

Comprendre les résultats de la couverture¶

À la fin du test de couverture, un rapport contenant les données de couverture recueillies devrait s'afficher :

Nom    Déclarations   Manquants   Branche   Partie   Couverture   Manquants
 ---------------------------------------------------
 TOTAL    7540 0   1040 0  100,0 %

Cela nous indique que la suite de tests a parcouru toutes les branches possibles du code. Cela ne garantit pas à 100 % l'absence de bogues, mais cela signifie que nous testons chaque ligne de code de la base de code.

Si vous apportez des modifications au code, il est possible que vous créiez une lacune dans cette couverture. Dans ce cas, le rapport de couverture vous indiquera quelles lignes ne sont pas exécutées. Par exemple, supposons que nous ayons apporté une modification à some/interesting_file.py, en ajoutant une nouvelle logique. Le rapport de couverture pourrait ressembler à ceci :

Nom Stmts   Miss Branch BrPart  Couverture   Manquant
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1 %   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 TOTAL 7540 1   1726 0  99,9 %

Cela signifie que la ligne 170, les lignes 302 à 307 et un saut de branche de la ligne 320 à la ligne 335 ne sont pas exécutés par la suite de tests. Vous devrez ajouter de nouveaux tests (ou modifier un test existant) pour rétablir cette couverture.

Rapport de couverture pour la plateforme hôte et la version de Python¶

Vous pouvez générer un rapport de couverture pour votre plateforme et votre version de Python. Par exemple, pour exécuter la suite de tests et générer un rapport de couverture sur Python 3.10, exécutez la commande suivante :

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Rapport de couverture pour la plateforme hôte¶

Si toutes les versions prises en charge de Python sont disponibles pour tox, la couverture pour la plate-forme hôte peut être générée en exécutant :

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Rapports de couverture au format HTML¶

Il est possible de générer un rapport de couverture HTML en ajoutant -html à n'importe quel nom d'environnement de couverture tox, par exemple :

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Il ne s'agit pas seulement d'écrire des tests !¶

Même si nous veillons à tester l'intégralité de notre code, notre travail ne consiste pas uniquement à maintenir ce niveau de test. Une partie de notre travail consiste à vérifier le code au fur et à mesure. On pourrait bien sûr écrire un ensemble complet de tests pour un gilet de sauvetage en béton… mais un gilet de sauvetage en béton resterait tout de même inutile pour l'usage auquel il est destiné !

Au fur et à mesure que vous développez des tests, vous devriez également vérifier que le module principal est cohérent en interne. Si vous remarquez des noms de méthodes qui ne sont pas cohérents en interne (par exemple, une méthode appelée on_select dans un module, mais on_selected dans un autre), ou si les données ne sont pas traitées de manière cohérente, signalez-le-nous en créant un ticket. Ou, si vous êtes sûr de savoir ce qu'il faut faire, créez une pull request qui corrige le problème que vous avez trouvé.

Si la résolution du problème nécessite des modifications de la documentation:

Créer la documentation

Avant d'apporter des modifications à la documentation de BeeWare, il est utile de confirmer que vous pouvez construire la documentation existante.

Vous devez avoir un interpréteur Python 3.13 installé et disponible sur votre chemin (c'est-à-dire que python3.13 doit démarrer un interpréteur Python 3.13).

BeeWare utilise tox pour construire la documentation. Les commandes tox suivantes doivent être lancées depuis le même emplacement que le fichier tox.ini, qui se trouve dans le répertoire racine du projet.

Aperçu de la documentation en direct¶

Pour faciliter l'édition rapide de la documentation, BeeWare dispose d'un mode "aperçu en direct".

L'aperçu en direct s'affichera avec des avertissements !

Le service en direct est disponible pour itérer sur les mises à jour de votre documentation. Pendant que vous mettez les choses à jour, vous pouvez introduire un problème de balisage. Les problèmes considérés comme WARNING feront échouer une compilation standard, cependant, le live serve est configuré pour indiquer les avertissements dans la sortie de la console, tout en continuant à construire. Cela vous permet d'itérer sans avoir à redémarrer la prévisualisation en direct.

Un WARNING est différent d'un ERROR. Si vous introduisez un problème qui est considéré comme un ERROR, le service en direct échouera et nécessitera un redémarrage. Il ne redémarrera pas tant que le problème WARNING n'aura pas été résolu.

Pour démarrer le serveur en direct :

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Cela permet de créer la documentation, de démarrer un serveur web pour diffuser la documentation et de surveiller le système de fichiers pour détecter toute modification apportée à la source de la documentation.

Une fois le serveur démarré, vous verrez quelque chose comme ce qui suit dans la sortie de la console :

INFO    -  [11:18:51] En cours de service sur http://127.0.0.1:8000/

Ouvrez un navigateur et accédez à l'URL fournie. Vous pouvez maintenant commencer à travailler sur la documentation. Si une modification est détectée, la documentation sera reconstruite et tout navigateur affichant la page modifiée sera automatiquement actualisé.

docs-live est une première étape

L'exécution de docs-live pour travailler avec le serveur live est destinée à l'itération initiale. Vous devriez toujours lancer une compilation locale avant de soumettre une pull request.

Construction locale¶

Une fois l'itération terminée, vous devrez procéder à une compilation locale de la documentation. Ce processus de construction est conçu pour échouer s'il y a des problèmes de balisage. Cela vous permet de rattraper tout ce que vous auriez pu manquer avec le serveur live.

Générer une version locale¶

Pour générer une version locale :

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Le résultat de cette compilation se trouvera dans le répertoire _build à la racine du projet.

Générer une version traduite locale¶

La documentation de BeeWare est traduite en plusieurs langues. Les mises à jour de la documentation en anglais peuvent entraîner des problèmes dans les versions en d'autres langues. Il est important de vérifier que toutes les versions fonctionnent avant de soumettre une demande de téléchargement.

Pour générer une compilation de toutes les traductions disponibles :

macOSLinuxWindows

(verbe) $ tox -e docs-all

(verbe) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Le résultat de la compilation de chaque langue se trouve dans le répertoire _build/html/<languagecode>, où <languagecode> est le code de langue à deux ou cinq caractères associé à la langue spécifique (par exemple fr pour le français, it pour l'italien, etc.)

Si vous trouvez un problème avec une seule version, vous pouvez lancer cette version séparément en exécutant tox -e docs-<languagecode>. Par exemple, pour compiler uniquement la documentation en français, lancez tox -e docs-<languagecode> :

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Le résultat d'une compilation en une seule langue se trouve dans le répertoire _build.

Linting de la documentation¶

Le processus de construction identifiera les problèmes Markdown, mais BeeWare effectue des vérifications supplémentaires pour le style et le formatage, connues sous le nom de "linting". Pour lancer les vérifications lint :

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Cela permettra de vérifier que la documentation ne contient pas de données :

hyperliens morts
mots mal orthographiés

Si une orthographe valide d'un mot est identifiée comme incorrecte, ajoutez le mot à la liste de docs/spelling_wordlist. Cela ajoutera le mot au dictionnaire du correcteur d'orthographe. Lorsque vous ajoutez un mot à cette liste, n'oubliez pas :

Nous préférons l'orthographe américaine, avec quelques libertés pour le langage familier spécifique à la programmation (par exemple, "apps") et le verbe des noms (par exemple, "scrollable").
Toute référence à un nom de produit doit utiliser la majuscule préférée du produit. (par exemple, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un terme est utilisé "comme un code", il doit être cité comme un littéral (comme ceci) plutôt que d'être ajouté au dictionnaire.

Rédiger la documentation

Voici les étapes à suivre pour rédiger votre contribution à la documentation de BeeWare.

Mise à jour de la documentation existante¶

Si vous éditez la documentation existante, vous devrez localiser le fichier dans le répertoire /docs/en. La structure du fichier suit la structure de la page, vous pouvez donc localiser le fichier en utilisant l'URL de la documentation.

Ajouter une nouvelle documentation¶

Si vous ajoutez un nouveau document, vous devez suivre quelques étapes supplémentaires.

Vous devrez créer le document à l'emplacement approprié dans le répertoire docs/en. Pour la discussion, nous dirons que vous ajoutez un nouveau document avec le nom de fichier new_doc.md.

Ensuite, vous devrez mettre à jour le fichier docs/fr/SUMMARY.md pour y inclure votre nouveau fichier. Le fichier SUMMARY.md est organisé de manière à refléter la structure du répertoire docs/en, mais, plus important encore, il détermine directement la structure de la barre latérale gauche. Si vous localisez la section où vous avez l'intention d'inclure new_doc.md, vous n'avez pas besoin de changer quoi que ce soit dans SUMMARY.md si vous voyez un chemin joker listé. Par exemple :

- ./chemin/vers/répertoire/*

Si la section dans laquelle vous avez l'intention d'inclure new_doc.md est une liste de liens Markdown individuels, vous devrez ajouter un lien explicite vers le vôtre. Par exemple :

- [Mon nouveau document](new_doc.md)

Rédiger votre documentation¶

Vous pouvez maintenant ouvrir le fichier souhaité dans votre éditeur et commencer à écrire.

Nous disposons d'un guide de style de la documentation qui décrit nos lignes directrices pour la rédaction de la documentation de BeeWare.

Lorsque vous êtes prêt à soumettre votre contribution:

Ajouter une note de modification

De nombreux outils BeeWare utilisent towncrier pour aider à la construction des notes de version pour chaque version. Lorsque vous soumettez une demande d'extraction à l'un des outils applicables, elle devra inclure une note de changement - cette note de changement deviendra l'entrée dans les notes de publication décrivant le changement qui a été fait.

Chaque demande d'extraction doit inclure au moins un fichier dans le répertoire changes/ qui fournit une courte description du changement implémenté par la demande d'extraction. La note de changement doit être au format Markdown, dans un fichier dont le nom est du format <id>.<fragment type>.md. Si le changement que vous proposez corrige un bogue ou implémente une fonctionnalité pour laquelle il existe un numéro de problème, l'ID sera le numéro de ce ticket. Si le changement n'a pas de problème correspondant, le numéro de PR peut être utilisé comme identifiant. Vous ne connaîtrez pas ce numéro de PR tant que vous n'aurez pas poussé la pull request, donc le premier passage du CI échouera la vérification towncrier ; ajoutez la note de changement et poussez une mise à jour du PR et le CI devrait alors passer.

Il existe cinq types de fragments :

feature : Le PR ajoute un nouveau comportement ou une nouvelle capacité qui n'était pas possible auparavant (par exemple, en ajoutant le support d'un nouveau format d'emballage, ou une nouvelle fonctionnalité dans un format d'emballage existant) ;
bugfix : Le PR corrige un bogue dans l'implémentation existante ;
doc : Le PR est une amélioration significative de la documentation ;
removal ; The PR represents a backward incompatible change in BeeWare API ; or the PR represents a backward incompatible change in BeeWare API. API ; ou
misc ; Un changement mineur ou administratif (par exemple, la correction d'une coquille, une clarification linguistique mineure, ou la mise à jour d'une version de dépendance) qui n'a pas besoin d'être annoncé dans les notes de publication.

Cette description dans la note de modification doit être un résumé "marketing" de haut niveau de la modification du point de vue de l'utilisateur, et non une description technique approfondie ou un détail d'implémentation. Elle se distingue d'un message de validation - un message de validation décrit ce qui a été fait afin que les futurs développeurs puissent suivre le raisonnement d'un changement ; la note de modification est une description à l'intention des utilisateurs, qui peuvent ne pas avoir connaissance des éléments internes.

Par exemple, si vous corrigez un bogue lié à la dénomination d'un projet, le message de validation pourrait être le suivant :

Appliquer une vérification d'expression régulière plus forte pour interdire les noms de projets qui commencent par des chiffres.

La note de modification correspondante se lirait comme suit :

Les noms de projets ne peuvent plus commencer par un chiffre.

Certains PR introduisent plusieurs fonctionnalités et corrigent plusieurs bogues, ou introduisent plusieurs changements incompatibles avec le passé. Dans ce cas, la PR peut avoir plusieurs fichiers de notes de modification. Si vous devez associer deux types de fragments au même identifiant, vous pouvez ajouter un suffixe numérique. Par exemple, si la PR 789 a ajouté une fonctionnalité décrite par le ticket 123, a corrigé un bug décrit par le ticket 234, et a également apporté deux changements incompatibles, vous pouvez avoir 4 fichiers de notes de changement :

123.feature.md
234.bugfix.md
789.removal.1.md
789.removal.2.md

Pour plus d'informations sur towncrier et les types de fragments, voir News Fragments. Vous pouvez également voir des exemples existants de fragments de nouvelles dans le répertoire changes du référentiel BeeWare. Si ce répertoire est vide, c'est probablement parce que BeeWare a récemment publié une nouvelle version ; les fichiers de notes de changement sont supprimés et combinés pour mettre à jour les notes de publication à chaque publication. Vous pouvez consulter ce fichier pour voir le style de commentaire requis ; vous pouvez consulter PRs récemment fusionnés pour voir comment formater vos notes de modification.

Soumettre une demande d'extraction

Maintenant que vous avez validé tous vos changements, vous êtes prêt à soumettre une demande d'extraction. Pour vous assurer que le processus de révision se déroule sans encombre, vous devez suivre un certain nombre d'étapes.

Travailler avec pre-commit¶

Lorsque vous validez une modification, la fonction pre-commit s'exécute automatiquement. Si des problèmes sont détectés lors de la validation, celle-ci échouera. Dans la mesure du possible, pre-commit effectuera les changements nécessaires pour corriger les problèmes qu'il a trouvés. Dans l'exemple suivant, un problème de formatage de code a été trouvé par la vérification ruff :

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

Dans ce cas, ruff a automatiquement corrigé le problème ; vous pouvez donc réajuster tous les fichiers qui ont été modifiés à la suite des vérifications avant validation, et valider à nouveau le changement. Cependant, certaines vérifications nécessiteront que vous fassiez des modifications manuelles. Une fois ces modifications effectuées, ajoutez à nouveau tous les fichiers modifiés et validez à nouveau.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Une fois que tout est passé, vous verrez un message indiquant que le commit a été finalisé, et votre journal git montrera votre commit comme l'ajout le plus récent. Vous êtes maintenant prêt à pousser sur GitHub.

Transférez vos modifications sur GitHub et créez votre demande d'extraction (pull request)¶

La première fois que vous envoyez une requête à GitHub, vous recevrez une URL qui vous mènera directement à la page de GitHub pour créer une nouvelle demande d'extraction. Suivez l'URL et créez votre demande d'extraction.

Voici un exemple de ce que l'on peut attendre de push, avec l'URL en surbrillance.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Si vous avez déjà poussé la branche courante sur GitHub, vous ne recevrez plus l'URL. Cependant, il existe d'autres moyens d'accéder à l'URL de création du PR :

Naviguez vers le dépôt amont, cliquez sur "Pull Requests" suivi de "New pull request", et choisissez le dépôt à partir duquel vous voulez soumettre votre pull request.
Si vous avez poussé récemment, naviguez vers le dépôt amont, repérez la bannière au-dessus de la liste des fichiers qui indique que le dépôt a "eu des poussées récentes", et cliquez sur le bouton "Comparez et faites une demande de traction".
Utilisez la commande GitHub CLI gh pr create, et répondez aux questions.
Utilisez la commande GitHub CLI gh pr create --web pour ouvrir un navigateur web vers la page de création du PR.

Chacune de ces options vous permettra de créer votre nouvelle demande d'extraction.

L'interface CLI GitHub : gh

GitHub fournit le GitHub CLI, qui vous permet d'accéder à de nombreuses fonctionnalités de GitHub depuis votre terminal, à travers la commande gh. La documentation de l'interface de programmation de GitHub couvre toutes les fonctionnalités.

Contenu de la demande d'extraction¶

Le titre d'une demande d'extraction doit être informatif, clair et concis. Essayez de le garder court si possible, mais des titres plus longs sont acceptables, si nécessaire. Un bon titre de PR devrait donner à une personne sans contexte une idée raisonnablement solide du bogue ou de la fonctionnalité implémentée par votre PR.

La description du PR doit refléter clairement les modifications apportées au PR. Une personne dépourvue de tout contexte doit pouvoir lire votre description et comprendre de manière relativement complète les raisons de la modification. Évitez les plaisanteries, les idiomes, les expressions familières et les mises en forme inutiles, comme l'utilisation de majuscules ou d'une ponctuation excessive ; il s'agit d'une explication directe de ce qui se passe dans votre RP, et le fait d'éviter ces éléments rend la description plus accessible à d'autres personnes.

S'il existe des cas de reproduction ou un régime de test que vous avez utilisé et qui ne fait pas déjà partie des changements présents dans le PR, ils doivent être expliqués et inclus dans le PR. L'explication doit inclure la manière de les exécuter et ce qu'il faut faire pour reproduire le résultat souhaité.

Si votre demande d'extraction résoudra le problème #1234, vous devriez inclure le texte Fixes #1234 dans la description de votre demande d'extraction. Cela entraînera la fermeture automatique du problème lorsque la demande sera fusionnée. Vous pouvez faire référence à d'autres discussions, problèmes ou demandes d'extraction en utilisant la même syntaxe #1234. Vous pouvez faire référence à un problème sur un dépôt différent en préfixant le numéro avec - par exemple python/cpython#1234 ferait référence au problème 1234 sur le dépôt CPython.

Intégration continue¶

*L'intégration continue est le processus qui consiste à effectuer des vérifications automatisées sur votre demande d'extraction. Il peut s'agir de vérifications simples, comme s'assurer que le code est correctement formaté, mais aussi de l'exécution de la suite de tests et de l'élaboration de la documentation.

Il existe un grand nombre de changements qui peuvent entraîner des échecs de l'IC. D'une manière générale, nous n'examinerons pas un PR qui ne passe pas l'IC. Si vous créez une demande d'extraction et que l'IC échoue, nous ne commencerons pas votre examen tant que l'IC ne sera pas passé. Si vos modifications entraînent un échec, il est de votre responsabilité d'en rechercher la raison et de résoudre le problème.

Lorsque l'IC échoue, les liens d'échec s'affichent au bas de la page PR, sous le titre "Some checks were not successful". Vous verrez une liste des vérifications échouées, qui apparaîtra en haut de la liste de toutes les vérifications s'il y a aussi des vérifications réussies. Si vous cliquez sur le lien d'échec, vous accéderez au journal. Le journal fournit souvent toutes les informations dont vous avez besoin pour déterminer la cause de l'échec. Lisez le journal et essayez de comprendre la raison de l'échec, puis faites le nécessaire pour le résoudre.

Il peut arriver qu'un contrôle CI échoue pour des raisons qui n'ont rien à voir avec vos modifications. Cela peut être dû à un problème sur la machine qui exécute le contrôle CI, ou parce que le contrôle CI est instable. Si vous constatez un échec, et que vous êtes certain qu'il n'est pas lié à vos modifications, ajoutez un commentaire à votre PR à cet effet, et nous l'examinerons.

Pour déclencher un nouveau cycle de CI, vous devez apporter de nouvelles modifications à votre branche.

Si vous vous trouvez dans une situation où vous avez besoin d'aide pour faire passer l'IC, laissez un commentaire sur le PR pour nous en informer et nous ferons notre possible pour vous aider.

Les contrôles pre-commit et `towncrier

Si les vérifications pre-commit ou towncrier échouent, cela bloquera la plupart des autres vérifications de CI. Vous devrez résoudre les problèmes applicables avant que l'ensemble des vérifications ne s'exécutent.

Nous avons des ressources limitées en matière de CI. Il est important de comprendre qu'à chaque fois que vous poussez vers la branche, le CI démarre. Si vous avez l'intention d'effectuer un certain nombre de modifications, il est préférable de les faire localement et de les pousser en une seule fois. Le CI ne s'exécutera que sur le commit le plus récent d'un lot, minimisant ainsi la charge sur notre système de CI.

Le processus de soumission de votre RP n'est pas terminé tant qu'il n'a pas été accepté par l'IC ou que vous ne pouvez pas expliquer pourquoi il ne l'a pas été.