Aperçu

Toutes les modifications apportées au code et à la documentation doivent être soumises via une pull request sur le dépôt GitHub du projet. dépôt GitHub du projet.

La plupart des projets disposent d'un guide de contribution spécifique avec des détails propres à ce projet ou à des types de contribution spécifiques. à ce projet ou à des types de contributions spécifiques. Cette documentation peut être trouvée sur Read the Docs. Par exemple, la [documentation de Briefcase documentation] (https://briefcase.readthedocs.io) contient des guides de contribution pour les deux code et documentation. documentation.

Toutes les soumissions doivent respecter le [Code de conduite de BeeWare] (/communauté/comportement/code de conduite/). conduite] (/community/behavior/code-of-conduct/).

Change Notes

Plusieurs projets BeeWare, notamment Briefcase et Toga, exigent que chaque demande de traction soit soumise avec une note de changement. soit soumise avec une note de changement. Ces notes de changement sont compilées lorsqu'une nouvelle version est créée pour le projet, produisant ainsi les les notes de version de la nouvelle version.

BeeWare utilise [Towncrier] (https://towncrier.readthedocs.io/en/stable/) pour gérer les notes de modification. gérer les notes de changement.

Un fichier de notes de modification doit être créé dans le répertoire changes et nommé selon le format suivant nommé selon ce format :

<PR/Issue #>.<Changement Type>.rst

Par exemple, une demande d'extraction qui corrige le problème GitHub #42 serait nommée 42.bugfix.rst. Si une demande d'extraction n'est pas associée à un problème spécifique, le numéro de la demande d'extraction peut être utilisé à la place. spécifique, le numéro de la demande d'extraction peut être utilisé à la place. Vous pouvez avoir besoin de créer la demande d'extraction sans note de modification pour obtenir un numéro de demande d'extraction attribué, puis pousser une mise à jour qui inclut la note de changement avec le numéro de demande d'extraction nouvellement attribué. le numéro de demande d'extraction nouvellement attribué.

Les types de modification pour la note de modification doivent être l'un des suivants :

  • feature
  • bugfix
  • doc
  • removal
  • misc

Le type misc est réservé aux changements qui n'affectent pas les utilisateurs, et n'ont pas besoin d'être mentionnés dans les notes de version. Corrections typographiques mineures dans la documentation, des mises à jour de la configuration de l'IC, et des corrections de bogues pour des fonctionnalités qui n'ont pas encore été officiellement publiées. pour des fonctionnalités qui n'ont pas encore été officiellement publiées. fonctionnalités qui seraient décrites en utilisant les marqueurs misc.

Une note de modification doit être une simple ligne de texte, fournissant un résumé de haut niveau de la modification du point de vue de l'utilisateur, et non pas un résumé approfondi. résumé de haut niveau du changement du point de vue de l'utilisateur, et non une pas une description technique approfondie ou un détail de mise en œuvre. Elle est distincte d'un message de validation. Un message de validation décrit ce qui a été fait afin que futurs développeurs puissent suivre le raisonnement d'un changement. Une note de modification est une description "orientée vers l'utilisateur", décrite en termes de nouvelles capacités disponible à la suite de la modification. Il peut être utile de considérer la comme un communiqué de presse annonçant le changement, plutôt que comme une description du commit.

Par exemple, si vous corrigez un bogue causé par la gestion de la date, le message de livraison ou la description de la demande de retrait pourrait être le suivant ou la description de la demande d'extraction pourrait être la suivante :

Ajout d'un validateur de format MM-DD-YYYY à la chaîne de validation du DateWidget chaîne.

Ceci décrit le changement qui a été apporté à l'implémentation - détail qui sera utile à la personne chargée d'examiner le code. Cependant, la note de modification correspondante pourrait se lire comme suit :

Les widgets de date peuvent maintenant accepter les dates au format US.

Il s'agit de décrire le changement fonctionnel tel qu'il sera vécu par les utilisateurs finaux. finaux. Un utilisateur peut lire cette description sans avoir besoin de savoir quoi que ce soit sur la mise en œuvre. de la mise en œuvre.

Code style

Les projets de BeeWare utilisent [Pre-commit] (https://pre-commit.com/) pour automatiser le respect du style du code. l'adhésion au style de code. Ces vérifications sont définies dans le fichier .pre-commit-config.yaml pour chaque dépôt et sont automatiquement automatiquement dans CI lorsqu'une Pull Request est ouverte.

Pour automatiser les vérifications Pre-commit dans votre environnement de développement local avec chaque commit git, exécutez pre-commit install.

Vérifications préalables à l'engagement incluses :

  • Noir assure un formatage uniforme du code
  • docformatter assure un formatage uniforme des chaînes de documents et des commentaires
  • pyupgrade assure que le code est utilise les meilleures pratiques les plus récentes pour Python
  • isort assure l'uniformité des déclarations import. uniformes
  • flake8 vérifie les problèmes de codage et de syntaxe de codage et de syntaxe
  • Vérifications diverses qui valident les documents structurés tels que les fichiers TOML et suppriment les espaces inutiles

Lignes directrices supplémentaires :

  • Éviter l'utilisation du "nous" dans les commentaires, par exemple "Loop over" plutôt que "We loop sur"

  • Utilisez des traits de soulignement, et non des majuscules, pour les noms de variables, de fonctions et de méthodes. méthode

  • Utilisez InitialCaps pour les noms de classes (ou pour les fonctions d'usine qui renvoient des classes)

  • Utiliser des docstrings de style Sphinx et 257 ; l'annotation de type avec 484 est optionnelle mais encouragée. facultative mais encouragée.

    Par exemple :

    def nom_de_la_fonction(param1 : int, param2 : str) -> bool :
    """Exemple de fonction avec des types et une docstring.

    :param param1 : Le premier paramètre.
    :param2 : Le deuxième paramètre.

    :returns : La valeur de retour. True pour un succès, False sinon.
    """

  • Dans les documents relatifs aux tests, indiquez le comportement attendu que chaque test test. N'incluez pas de préambules tels que "teste que" ou "s'assure que". que".

  • Réserver les références des tickets aux problèmes obscurs pour lesquels le ticket contient des détails supplémentaires qui ne peuvent pas être facilement décrits dans les documentations ou les documents. détails supplémentaires qui ne peuvent pas être facilement décrits dans les docstrings ou les commentaires. Inclure le numéro de ticket à la fin d'une phrase comme ceci :

    def test_foo() :
    """Une docstring de test ressemble à ceci (#123456)."""

  • Sauf indication contraire, suivez les instructions 8 (en accordant une attention particulière aux instructions suivantes Section 2).