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

Votre demande de modification peut nécessiter des informations supplémentaires, telles qu'une note de modification, avant de pouvoir être examinée.