Mise en œuvre d'une nouvelle fonctionnalité¶

Une fois le processus de proposition terminé, vous devriez disposer d'un projet complet pour une nouvelle fonctionnalité. Il est donc temps de commencer à rédiger !

Si votre fonctionnalité nécessite une mise en œuvre spécifique à une plateforme, le processus de proposition devrait avoir validé le fait que l'idée pourrait être mise en œuvre sur toutes les plateformes. Cependant, en tant que personne qui met en œuvre une nouvelle fonctionnalité pour la première fois, vous n'êtes pas responsable de la mise en œuvre de la nouvelle fonctionnalité pour toutes les plateformes. Vous devez fournir une implémentation complète pour au moins une plateforme, y compris les tests. Pour toutes les autres plateformes, vous devrez fournir une implémentation "stub" - une implémentation qui fournit la définition de l'interface nue, mais qui lève une erreur NotImplementedError ou affiche un message de journal indiquant que le comportement n'est pas implémenté sur cette plateforme.

Une partie importante de la mise en œuvre d'une nouvelle fonctionnalité consiste à s'assurer que cette fonctionnalité est entièrement documentée. Au minimum, cela signifie qu'il faut s'assurer qu'il existe une documentation sur l'API, mais cela peut également nécessiter l'ajout d'un guide pratique ou d'un guide thématique.

Contribuer à la création de nouvelles fonctionnalités¶

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

Évitez les dérives de périmètre

On parle de "Scope creep" lorsque la liste des problèmes résolus ou des fonctionnalités implémentées par une seule contribution s'allonge considérablement au-delà de ce qui était prévu au début du travail. Vous commencez par un simple problème ; vous découvrez un problème étroitement lié et décidez d'inclure également cette correction ; puis un troisième… avant même de vous en rendre compte, vous avez une demande d'extension qui clôt 5 problèmes et ajoute 3 nouvelles fonctionnalités, y compris des douzaines de fichiers.

Tout le monde est confronté à des problèmes d'envergure. C'est un concept qui n'est que trop familier aux développeurs chevronnés ; nous l'avons tous expérimenté à de multiples reprises et avons connu tous les problèmes qui en découlent.

Il existe des raisons très pratiques d'éviter l'élargissement du champ d'application. Plus une contribution est importante, plus il est difficile de travailler avec elle. Il devient plus difficile d'identifier les exceptions ou les problèmes potentiels, ce qui signifie que la qualité globale de la contribution peut être diminuée. Les révisions deviennent également plus difficiles lorsque l'examinateur doit traiter de multiples contextes, potentiellement sans rapport entre eux. Une contribution plus importante signifie plus de commentaires de révision, et en tant que contributeur, il peut devenir difficile de suivre plusieurs fils de révision. Même votre expérience GitHub en souffrira - l'interface utilisateur de GitHub ralentira au fur et à mesure que la taille d'un PR augmentera, ce qui signifie qu'il sera de plus en plus difficile de naviguer dans les fichiers à travers l'interface GitHub et de tenter de laisser des commentaires de révision.

Chaque fois que vous trouvez une raison d'ajouter quelque chose à votre contribution qui ne fait pas explicitement partie de la proposition originale ou du rapport de bogue, vous devez vous demander si vous ne vous dirigez pas vers un élargissement du champ d'application. Existe-t-il deux fonctionnalités distinctes qui pourraient être mises en œuvre séparément ? Une fonctionnalité peut-elle être implémentée avec une limitation ou un bogue connu, et ce bogue corrigé dans une demande de suivi ? Une partie de la correction d'un bogue est-elle indépendante d'une autre ? Si une partie d'un changement peut être laissée de côté sans altérer la contribution originale, elle devrait probablement l'être.

Le développement d'un logiciel est toujours un processus d'amélioration progressive. Chaque contribution individuelle doit laisser la base de code dans un meilleur état après avoir été fusionnée, mais il est tout à fait acceptable de laisser des bogues ou des parties de fonctionnalités comme travail pour une amélioration future. Cela peut signifier diviser une demande d'extraction en plusieurs parties qui peuvent être examinées indépendamment, ou enregistrer un problème afin que quelqu'un d'autre puisse l'examiner et le résoudre.

Limiter la portée de chaque contribution est bénéfique pour toutes les personnes impliquées, y compris vous. Vos évaluateurs, et vous-même, l'apprécierez.

Mettre en œuvre la nouvelle fonctionnalité

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.

///

/// 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.

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é.