Ajouter de la documentation¶

Vous avez beau avoir le meilleur logiciel du monde, si personne ne sait comment l'utiliser, à quoi bon ? La documentation peut toujours être améliorée - et nous avons besoin de votre aide !

Documentation formulaires¶

La documentation de BeeWare est rédigée à l'aide de MkDocs et Markdown. Nous nous efforçons de suivre le cadre Diataxis pour structurer la documentation.

Le cadre Diataxis décrit quatre "formes" de documentation :

Tutoriel - Une expérience d'apprentissage guidée, avec un objectif de projet spécifique.
Guide pratique - Instructions qui guident le lecteur vers un objectif ou un résultat spécifique.
Guide thématique - Discussion d'une seule idée, expliquée de manière à ce que les concepts sous-jacents soient clairs.
Référence - Descriptions techniques d'API spécifiques ou d'autres interfaces.

Avant de commencer à contribuer à la documentation, il est important d'identifier la forme qui convient le mieux. De nombreuses propositions de documentation seront initialement décrites comme une demande de "tutoriel sur X" - mais dans la plupart des cas, il s'agit en fait d'un mode d'emploi, d'un guide thématique ou d'informations de référence améliorées.

Prenons l'exemple de la rédaction d'une documentation sur la cuisson des biscuits.

Tutoriel¶

Un tutoriel est une introduction, particulièrement destinée aux débutants, dont l'objectif est d'amener le lecteur d'un point de départ propre à un produit fini. Il nécessite des instructions très précises et des explications détaillées qui replacent les étapes du tutoriel dans leur contexte. Vous ne devez rien présumer de l'expérience du lecteur avec l'outil expliqué, bien qu'il soit raisonnable de supposer une connaissance de base de Python.

Le didacticiel doit contenir des points de contrôle réguliers permettant au lecteur de s'assurer qu'il a réussi à faire ce qui est décrit. À chaque point de contrôle, les critères de réussite doivent être clairs. Les cas d'échec connus doivent être clairement décrits, avec des explications sur les erreurs ou les problèmes probables que le lecteur pourrait rencontrer. Les éléments qui changent à la suite des actions entreprises par le lecteur doivent être signalés, même s'ils semblent évidents. La répétition est encouragée, en particulier si vous essayez d'établir une meilleure pratique ou des processus communs. Les explications sur les éléments internes doivent être évitées, de même que les chemins alternatifs menant au même résultat.

Un tutoriel sur la cuisson des biscuits est plus qu'une simple recette. Les instructions d'un tutoriel doivent être accessibles à quelqu'un qui n'a jamais fait de pâtisserie auparavant (un enfant, par exemple) et doivent tenir compte de choses qu'un pâtissier expérimenté considérerait comme allant de soi, comme la façon de crémer le sucre et le beurre, le processus de préchauffage du four ou le temps de refroidissement des biscuits avant de les déguster. L'objectif du didacticiel n'est pas de produire un biscuit, mais de transmettre les principes fondamentaux de la pâtisserie. Le biscuit qui en résulte est la délicieuse friandise qui convainc quelqu'un d'entreprendre le tutoriel en premier lieu.

Guide pratique¶

Un guide pratique doit se concentrer sur un cas d'utilisation spécifique dans le monde réel et sur des résultats pratiques, plutôt que sur des explications théoriques. Contrairement à un didacticiel, vous pouvez supposer une certaine familiarité avec les outils existants. Le lecteur doit être en mesure de suivre le guide du début à la fin et d'atteindre l'objectif, mais il peut avoir besoin de certaines connaissances préalables pour y parvenir. Le guide doit comprendre un ensemble d'instructions concrètes ou d'étapes logiques à suivre pour atteindre l'objectif fixé.

Une recette dans un livre de cuisine est un bon exemple de guide pratique. Il existe de nombreuses recettes de biscuits aux pépites de chocolat et elles présentent toutes des caractéristiques communes, mais toute recette spécifique doit pouvoir être suivie du début à la fin et aboutir à un résultat cohérent. Une bonne recette de cookies aux pépites de chocolat ne s'attardera pas sur les mérites relatifs des différents types de sucre ou de farine, et ne donnera pas d'instructions détaillées sur la technique ou le processus de base ; elle ne contiendra que les ingrédients et les instructions nécessaires à la préparation d'une fournée de cookies, en supposant que le lecteur possède des connaissances de base en matière de pâtisserie.

Guide thématique¶

Un guide thématique décrit un seul sujet ou une seule idée. Il peut inclure des exemples de code ou d'instructions, mais il est beaucoup plus axé sur la fourniture d'une image de haut niveau d'un concept global. Il peut inclure des opinions et d'autres points de vue, mais il doit rester centré sur le sujet spécifique du guide.

Un guide thématique sur la cuisson des biscuits pourrait se pencher sur l'histoire des biscuits en tant que produits de boulangerie, explorer la façon dont les processus industrialisés donnent lieu à différents types de biscuits par rapport aux biscuits faits maison, ou suggérer des façons d'incorporer les biscuits dans un régime alimentaire équilibré. En soi, ce document ne serait pas très utile à suivre si vous vouliez préparer un biscuit, mais il pourrait fournir le contexte qui permettrait à une personne familiarisée avec la pâtisserie de personnaliser avec succès une recette de biscuit existante.

Référence¶

La documentation de référence est orientée vers l'information, décrivant les spécificités du fonctionnement d'une bibliothèque d'outils. Elle peut souvent être générée à partir du code lui-même, mais une bonne documentation sur l'API peut nécessiter des explications et un contexte supplémentaires. Bien qu'elle puisse parfois inclure des exemples d'utilisation, les explications détaillées doivent être évitées.

Un guide de référence sur la pâtisserie pourrait décrire les types de sucre qui peuvent être utilisés et détailler leurs propriétés lorsqu'ils sont utilisés dans la pâtisserie. Il décrirait des faits concrets sur le sucre, mais une discussion plus large sur le choix des types de sucre devrait faire l'objet d'un guide pratique ou thématique. Les informations nutritionnelles que l'on trouve sur la plupart des aliments emballés seraient considérées comme une documentation de référence.

Style de documentation¶

La documentation de BeeWare suit les lignes directrices décrites dans le guide de style de la documentation. Ce guide inclut le style et le formatage de base, ainsi que le processus de vérification de l'orthographe. Il couvre également divers détails de la syntaxe Markdown, tels que la syntaxe des liens de référence, des conseils pour travailler avec des blocs de code et la gestion des images.

Contribuer à la documentation¶

Proposer une nouvelle documentation

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

Faites vos recherches¶

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

Discuter de l'idée¶

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

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

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

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

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

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

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

Transformer en demande formelle de fonctionnalité¶

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

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

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.

Documentation relative au bâtiment

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

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

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

Aperçu de la documentation en direct¶

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

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

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

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

Pour démarrer le serveur en direct :

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

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

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

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

INFO    -  [11:18:51] 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édaction de 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é.