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 :

$ python3 --version

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 :

$ python3 --version

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/<your username>/beeware.git

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

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

$ git clone https://github.com/<your username>/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/<your username>/beeware.git

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

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

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

• pre-commit hooks
• towncrier release note check

• documentation linting

• test suite for available Python versions

• code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations

Run tests for multiple versions of Python

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
TOTAL 7540 0 1040 0 100,0% 0

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

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

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

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

/// details-abstract | 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".

/// warning | 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 :



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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 :

- ./path/to/directory/*

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 :

- [My new 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é.