Lignes directrices sur les demandes d'extraction #

Les demandes d'extraction (PR) sont le mécanisme de contribution au code et à la documentation de Matplotlibs.

Résumé pour les auteurs de pull request #

Noter

  • Nous apprécions les contributions de personnes de tous niveaux d'expérience. En particulier, s'il s'agit de votre premier PR, tout ne doit pas être parfait. Nous vous guiderons tout au long du processus de relations publiques.

  • Néanmoins, veuillez essayer de suivre au mieux les directives ci-dessous pour aider à rendre le processus de relations publiques rapide et fluide.

  • Soyez patient avec les examinateurs. Nous faisons de notre mieux pour répondre rapidement, mais nous avons une bande passante limitée. S'il n'y a pas de commentaires dans quelques jours, veuillez nous envoyer un ping en publiant un commentaire sur votre PR.

Lorsque vous faites un PR, faites attention à :

  • Ciblez la branche principale .

  • Respectez les directives de codage .

  • Mettre à jour la documentation si nécessaire.

  • Essayez de rendre le PR aussi "prêt à l'emploi" que possible. Cela permet d'accélérer le processus d'examen.

  • Vous pouvez ouvrir des relations publiques incomplètes ou en cours si vous avez besoin d'aide ou de commentaires des développeurs. Vous pouvez les marquer comme des brouillons de demandes d'extraction sur GitHub.

  • Lors de la mise à jour de votre PR, au lieu d'ajouter de nouveaux commits pour corriger quelque chose, veuillez envisager de modifier votre ou vos commits initiaux pour garder l'historique propre. Vous pouvez y parvenir en utilisant

    git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease

Voir aussi Contribuer pour savoir comment faire un PR.

Résumé pour les réviseurs de pull request #

Noter

  • Si vous avez des droits de validation, vous êtes autorisé à les utiliser. Aidez-nous à réviser et à fusionner les PR !

  • Soyez patient et gentil avec les contributeurs.

Sujets de contenu :

  • La fonctionnalité / correction de bogue est-elle raisonnable ?

  • Le PR est-il conforme aux directives de codage ?

  • La documentation (docstrings, exemples, nouveautés, modifications de l'API) est-elle mise à jour ?

Thèmes organisationnels :

Directives détaillées #

Documents #

  • Chaque nouvelle fonctionnalité doit être documentée. S'il s'agit d'un nouveau module, n'oubliez pas d'ajouter un nouveau premier fichier à la documentation de l'API.

  • Chaque fonction de traçage de haut niveau doit avoir un petit exemple dans la Examplessection de la docstring. Cela devrait être aussi simple que possible pour démontrer la méthode. Les exemples plus complexes doivent aller dans un fichier d'exemple dédié dans le examplesrépertoire, qui sera rendu dans la galerie d'exemples de la documentation.

  • Créez les documents et assurez-vous que tous les avertissements de formatage sont traités.

  • Voir Rédaction de documentation pour notre guide de style de documentation.

  • Si votre modification est une nouvelle fonctionnalité majeure, ajoutez une entrée à doc/users/whats_new.rst.

  • Si vous modifiez l'API d'une manière incompatible avec les versions antérieures, veuillez le documenter en ajoutant un fichier dans le sous-répertoire approprié de doc/api/next_api_changes/, probablement dans le sous- behavior/ répertoire .

Étiquettes #

  • Si vous avez le droit de définir des étiquettes, étiquetez le PR avec des étiquettes descriptives. Voir la liste des étiquettes .

  • Si le PR apporte des modifications à l'action de construction de la roue, ajoutez l'étiquette "Exécuter cibuildwheel" pour activer les roues de test.

Jalons #

  • Définissez le jalon selon ces règles :

    • Les nouvelles fonctionnalités et les modifications de l'API sont jalonnées pour la prochaine version mineure v3.X.0.

    • Les corrections de bogues et les changements de docstring sont jalonnés pour la prochaine version du correctifv3.X.Y

    • Les modifications de la documentation (tous les fichiers .rst et les exemples) sont jalonnées v3.X-doc

    Si plusieurs règles s'appliquent, choisissez la première correspondance dans la liste ci-dessus.

    La définition d'un jalon n'implique ni ne garantit qu'un PR sera fusionné pour cette version, mais s'il devait être fusionné, dans quelle version il se trouverait.

    Tous ces PR doivent cibler la branche principale. La balise de jalon déclenche un rétroportage automatique pour les jalons qui ont une branche correspondante.

Fusion #

  • La documentation et les exemples peuvent être fusionnés par le premier examinateur. Utilisez le seuil "est-ce mieux qu'il ne l'était ?" comme critères d'examen.

  • Pour les modifications de code (tout ce qui se trouve dans srcou lib), au moins deux développeurs principaux (ceux qui ont des droits de validation) doivent examiner toutes les demandes d'extraction. Si vous êtes le premier à examiner une PR et à approuver les modifications, utilisez l' outil "approuver l'examen" de GitHub pour le marquer comme tel. Si vous êtes un réviseur ultérieur, veuillez approuver la révision et si vous pensez qu'aucune autre révision n'est nécessaire, fusionnez le PR.

    Assurez-vous que toutes les modifications de l'API sont documentées dans un fichier dans l'un des sous-répertoires de doc/api/next_api_changes, et que les nouvelles fonctionnalités importantes ont une entrée dans doc/user/whats_new.

    • Si un PR a déjà une évaluation positive, un développeur principal (par exemple, le premier examinateur, mais pas nécessairement) peut défendre ce PR pour la fusion. Pour ce faire, ils doivent envoyer un ping à tous les développeurs principaux à la fois sur GitHub et sur la liste de diffusion des développeurs, et étiqueter le PR avec le "Fusionner avec une seule révision ?" étiquette. Les autres développeurs de base peuvent alors soit examiner le PR et le fusionner ou le rejeter, soit simplement demander qu'il reçoive un deuxième examen avant d'être fusionné. Si personne ne demande un tel deuxième examen dans un délai d'une semaine, le PR peut alors être fusionné sur la base de cet examen unique.

      Un développeur principal ne devrait défendre qu'un seul PR à la fois et nous devrions essayer de maintenir un flux raisonnable de PR défendus.

  • Ne pas fusionner soi-même, sauf pour les "petits" correctifs pour débloquer le CI ou lorsqu'un autre réviseur l'autorise explicitement (par exemple, "Approuver le passage du CI modulo, peut fusionner automatiquement lorsqu'il est vert").

Tests automatisés #

Chaque fois qu'une demande d'extraction est créée ou mise à jour, divers outils de test automatisés s'exécutent sur toutes les plates-formes et versions de Python prises en charge.

  • Assurez-vous que les pipelines Linting, GitHub Actions, AppVeyor, CircleCI et Azure passent avant la fusion (toutes les vérifications sont répertoriées au bas de la page GitHub de votre demande d'extraction). Voici quelques conseils pour trouver la cause de l'échec du test :

    • Si Linting échoue, vous avez un problème de style de code, qui sera répertorié sous forme d'annotations sur le diff de la demande d'extraction.

    • Si une exécution GitHub Actions ou AppVeyor échoue, recherchez dans le journal FAILURES. La section suivante contiendra des informations sur les tests échoués.

    • Si CircleCI échoue, vous avez probablement un problème de style reStructuredText dans la documentation. Recherchez dans le journal CircleCI WARNING.

    • Si les pipelines Azure échouent avec une erreur de comparaison d'images, vous pouvez trouver les images en tant qu'artefacts de la tâche Azure :

      • Cliquez sur Détails sur la case à cocher sur la page GitHub PR.

      • Cliquez sur Afficher plus de détails sur Azure Pipelines pour accéder à Azure.

      • Sur la page de présentation, les artefacts sont répertoriés dans la section Related .

  • Codecov et LGTM sont actuellement à titre indicatif. Leur échec n'est pas forcément un bloqueur.

  • tox n'est pas utilisé dans les tests automatisés. Il est pris en charge pour les tests locaux.

  • Si vous savez que vos modifications n'ont pas besoin d'être testées (c'est très rare !), tous les CI peuvent être ignorés pour un commit donné en incluant ou dans le message de commit. Si vous savez que seul un sous-ensemble de CI doit être exécuté (par exemple, si vous modifiez un bloc de reStructuredText simple et que vous souhaitez que seul CircleCI s'exécute pour rendre le résultat), les CI individuels peuvent également être ignorés lors de validations individuelles en utilisant ce qui suit sous-chaînes dans les messages de validation :[ci skip][skip ci]

    • Actions GitHub :[skip actions]

    • AppVeyor : (doit être dans la première ligne du commit)[skip appveyor]

    • Pipelines Azure :[skip azp]

    • CercleCI :[skip circle]

Nombre de commits et squashing #

  • L'écrasement est au cas par cas. L'équilibre est entre la charge du contributeur, le maintien d'un historique relativement propre et le maintien d'un historique utilisable pour la bissectrice. La seule fois où nous sommes vraiment stricts à ce sujet est d'éliminer les fichiers binaires (par exemple plusieurs régénérations d'images de test) et de supprimer les fusions en amont.

  • Ne laissez pas le parfait être l'ennemi du bien, en particulier pour la documentation ou les exemples de relations publiques. Si vous vous retrouvez à faire de nombreuses petites suggestions, ouvrez un PR contre la branche d'origine, poussez les modifications vers la branche contributrice, ou fusionnez le PR puis ouvrez un nouveau PR contre l'amont.

  • Si vous poussez vers une branche contributeur laissez un commentaire expliquant ce que vous avez fait, ex "j'ai pris la liberté de pousser un petit PR de nettoyage vers votre branche, merci pour votre travail.". Si vous envisagez d'apporter des modifications substantielles au code ou à l'intention du PR, veuillez d'abord vérifier auprès du contributeur.

Branches et backports #

Succursales actuelles #

Les branches actives actuelles sont

principale

La version de développement actuelle. Les futures versions mineures ( v3.N.0 ) en seront dérivées.

v3.Nx

Branche de maintenance pour Matplotlib 3.N. Les futures versions de correctifs en seront dérivées.

v3.NM-doc

Documentation de la version actuelle. Sur une version de correctif, cela sera remplacé par une branche correctement nommée pour la nouvelle version.

Sélection de branche pour les pull requests #

En règle générale, toutes les demandes d'extraction doivent cibler la branche principale.

Les autres branches sont alimentées en automatique ou en manuel . Le ciblage direct d'autres branches n'est que rarement nécessaire pour des travaux de maintenance particuliers.

Stratégie de rétroportage #

Nous rétroporterons toujours vers la branche de publication des correctifs ( v3.Nx ):

  • corrections de bogues critiques (erreur de segmentation, échec de l'importation, problèmes que l'utilisateur ne peut pas contourner)

  • correctifs pour les régressions par rapport aux deux dernières versions.

Tout le reste (régressions par rapport aux anciennes versions, bugs/incohérences d'api que l'utilisateur peut contourner dans son code) est au cas par cas, devrait être à faible risque et nécessite quelqu'un pour défendre et guider le backport.

Les seules modifications à rétroporter dans la branche documentation ( v3.NM-doc ) sont les modifications apportées à doc, examplesou tutorials. Toute modification apportée libou srcincluant uniquement les modifications de docstring ne doit pas être rétroportée sur cette branche.

Rétroportages automatisés #

Nous utilisons le bot meeseeksdev pour rétroporter automatiquement les fusions vers la base de branche de maintenance correcte sur le jalon. Pour fonctionner correctement, le jalon doit être défini avant la fusion. Si vous avez des droits de validation, le bot peut également être déclenché manuellement après une fusion en laissant un message sur le PR. S'il y a des conflits, meeseekdevs vous informera que le rétroportage doit être fait manuellement.@meeseeksdev backport to BRANCH

La branche cible est configurée en plaçant la description du jalon sur sa propre ligne.on-merge: backport to TARGETBRANCH

Si le bot ne fonctionne pas comme prévu, veuillez signaler les problèmes à Meeseeksdev .

Rétroportages manuels #

Lorsque vous effectuez des rétroportages, veuillez copier le formulaire utilisé par meeseekdev, . Si vous devez résoudre manuellement des conflits, notez-les et indiquez comment vous les avez résolus dans le message de validation.Backport PR #XXXX: TITLE OF PR

Nous effectuons un rétroportage de main vers v2.2.x en supposant :

  • matplotlibest une branche distante en lecture seule du dépôt matplotlib/matplotlib

Il TARGET_SHAs'agit du hachage du commit de fusion que vous souhaitez rétroporter. Cela peut être lu sur la page GitHub PR (dans l'interface utilisateur avec la notification de fusion) ou via les outils CLI git.

En supposant que vous ayez déjà une branche locale v2.2.x(sinon, alors ), et que votre télécommande pointant vers s'appelle :git checkout -b v2.2.xhttps://github.com/matplotlib/matplotlibupstream

git fetch upstream
git checkout v2.2.x  # or include -b if you don't already have this.
git reset --hard upstream/v2.2.x
git cherry-pick -m 1 TARGET_SHA
# resolve conflicts and commit if required

Les fichiers en conflit peuvent être répertoriés par , et devront être corrigés à la main (recherche sur ). Une fois le conflit résolu, vous devrez rajouter le(s) fichier(s) à la branche puis continuer la sélection :git status>>>>>

git add lib/matplotlib/conflicted_file.py
git add lib/matplotlib/conflicted_file2.py
git cherry-pick --continue

Utilisez votre discrétion pour pousser directement en amont ou pour ouvrir un PR ; veillez à pousser ou PR contre la v2.2.xbranche amont, non main!