Flux de travail de contribution à GitHub pour les changements majeurs ou à long terme

  • Article

Important

Tous les dépôts qui publient sur Microsoft Learn ont adopté le Code de conduite Microsoft Open Source ou le Code de conduite de .NET Foundation. Pour plus d’informations, consultez les questions fréquentes (FAQ) sur le code de conduite. Vous pouvez aussi envoyer vos questions ou vos commentaires à opencode@microsoft.com ou à conduct@dotnetfoundation.org.

Les learn.microsoft.com conditions d’utilisation couvrent les corrections mineures ou les clarifications apportées à la documentation et aux exemples de code dans les dépôts publics. Les nouveautés ou modifications significatives génèrent un commentaire dans la demande de tirage qui vous invite à signer un contrat de licence de contribution en ligne si vous n’êtes pas un employé de Microsoft. Vous devrez remplir le formulaire en ligne pour que nous puissions accepter votre requête de tirage (pull request).

Vue d'ensemble

Ce flux de travail convient pour un contributeur qui a besoin de faire un changement majeur ou qui sera un contributeur fréquent d’un dépôt. Les contributeurs fréquents ont généralement des changements continus (à long terme) qui peuvent passer par plusieurs cycles de création/validation/préproduction ou être répartis sur plusieurs jours avant la validation et la fusion de la demande de tirage.

Voici des exemples de ce type de contribution :

  • Apport d’une grande contribution. Par exemple, vous pouvez apporter des contributions (ajouts, modifications ou suppressions) qui englobent plusieurs articles et qui doivent être validées et testées comme une seule unité de travail dans une même demande de tirage.
  • Création et publication d’un nouvel article, qui nécessite généralement un éditeur local plus robuste.
  • Ajout de nouvelles images ou mise à jour d’images, qui nécessite généralement la création simultanée d’un nouveau sous-répertoire media, des fichiers image, les mises à jour des liens vers les images dans des articles et la prévisualisation des fichiers Markdown dans un éditeur local pour tester l’affichage des images.
  • Mise à jour d’un article sur plusieurs jours avant la publication. Normalement dans ce cas, vous devez intégrer régulièrement d’autres modifications qui interviennent dans la branche par défaut. Cette intégration est plus facile si vous utilisez Git Bash et l’édition locale. Vous courez également le risque de perdre vos modifications si vous utilisez l’interface utilisateur de GitHub et d’attendre avant de pouvoir valider vos modifications.
  • Des mises à jour apportées en continu au même article après l’ouverture d’une demande de tirage (sauf si vous êtes suffisamment à l’aise pour utiliser l’interface utilisateur de GitHub). L’utilisation de l’interface utilisateur de GitHub peut potentiellement créer plusieurs demandes de tirage en attente pour le même fichier, ce qui peut aboutir à des conflits entre elles.

Terminologie

Avant de commencer, passons en revue quelques-uns des termes et monikers de Git/GitHub utilisés dans ce flux de travail. Vous n'avez pas à les comprendre dès maintenant. Sachez juste que vous allez les étudier et que vous pouvez revenir à cette section quand vous souhaitez vérifier une définition.

Nom Description
duplication (fork) Normalement utilisé comme nom lorsqu'il est fait référence à une copie d'un dépôt GitHub principal. En pratique, une duplication (fork) est simplement un autre dépôt. Mais il est particulier en cela que GitHub conservez une connexion avec le dépôt principal/parent. Ce terme est parfois utilisé sous forme verbale, par exemple « Vous devez d’abord dupliquer le dépôt ».
remote Une connexion nommée à un dépôt distant, comme les remotes « origin » et « upstream ». Git les appelle « remotes », car elles servent à référencer un dépôt hébergé sur un autre ordinateur. Dans ce flux de travail, une connexion remote concerne toujours un dépôt GitHub.
origin Nom affecté à la connexion entre votre dépôt local et le dépôt à partir duquel il a été cloné. Dans ce flux de travail, origin représente la connexion à votre embranchement. Il s’agit parfois du moniker pour le dépôt d’origine lui-même, par exemple dans la phrase « N’oubliez pas d’envoyer vos modifications sur origin ».
upstream Comme pour la connexion remote origin, upstream est le nom d'une connexion vers un autre référentiel. Dans ce flux de travail, upstream représente la connexion entre votre référentiel local et le référentiel principal, à partir duquel votre embranchement a été créé. Il s’agit parfois du moniker pour le dépôt ascendant lui-même, par exemple dans la phrase « N’oubliez pas d’extraire les modifications de l’amont ».

Flux de travail

Important

Si vous ne l’avez pas déjà fait, vous devez effectuer les étapes de la section Configuration. Cette section vous guide lors de la configuration de votre compte GitHub, l’installation de Git Bash et d’un éditeur Markdown, la création d’une duplication et la configuration de votre dépôt local. Si vous découvrez les concepts de Git et GitHub, comme les dépôts ou les branches, consultez d’abord les Bases de Git et GitHub.

Dans ce flux de travail, les changements circulent dans un cycle répétitif. En partant du référentiel local de votre appareil, ils passent par votre branche GitHub, dans le référentiel GitHub principal, puis reviennent localement lorsque vous intégrez les modifications d'autres contributeurs.

Utiliser le flux GitHub

Rappelez-vous, comme indiqué dans les Bases de Git et GitHub, qu’un dépôt Git contient une branche par défaut et des branches supplémentaires en cours de modification qui n’ont pas été intégrées à la branche principale. Quand vous introduisez une série de changements liés logiquement, une bonne pratique consiste à créer une branche de travail pour gérer vos modifications via le flux de travail. Nous l’appelons ici branche de travail, car il s’agit d’un espace de travail pour répéter/affiner les modifications, jusqu’à ce qu’elles puissent être réintégrées à la branche par défaut.

Isoler les changements liés dans une branche spécifique vous permet de contrôler et d'introduire ces changements de façon indépendante, en les ciblant pour une date de publication particulière dans le cycle de publication. En réalité, en fonction du type de travail que vous faites, vous pouvez facilement vous retrouver avec plusieurs branches de travail dans votre dépôt. Il n’est pas rare de travailler sur plusieurs branches en même temps, chacune représentant un projet différent.

Conseil

L’insertion de modifications dans la branche par défaut n’est pas une bonne pratique. Supposons que vous utilisez la branche par défaut pour introduire une série de changements pour une publication de fonctionnalité planifiée. Vous terminez les modifications et attendez de les publier. Entre-temps, vous recevez une demande urgente de correction. Vous apportez donc la modification à un fichier dans la branche par défaut et publiez la modification. Dans cet exemple, vous publiez par erreur à la fois le correctif et les modifications que vous attendiez de publier à une date précise.

Créons maintenant une nouvelle branche de travail dans votre référentiel local pour capturer les modifications que vous proposez. Si vous avez configuré Git Bash (voir Installer les outils de création de contenu), vous pouvez créer une branche et « extraire » cette branche avec une commande à partir de votre dépôt cloné :

git checkout -b "branchname"

Chaque client Git est différent : consultez l’aide du client choisi. Vous trouverez une vue d’ensemble du processus dans le Guide de GitHub sur Flux GitHub.

Apporter vos changements

Maintenant que vous avez une copie (« clone ») du dépôt Microsoft et que vous avez créé une branche, vous pouvez désormais apporter les changements qui, selon vous, seraient utiles à la communauté en utilisant n’importe quel éditeur de texte ou Markdown, comme indiqué dans la page Installer les outils de création de contenu. Vous pouvez enregistrer vos changements localement sans avoir à les envoyer à Microsoft tant que vous n’êtes pas prêt.

Enregistrement des changements dans votre dépôt

Avant d’envoyer vos changements à l’auteur, vous devez d’abord les enregistrer dans votre dépôt Github. Là encore, même si tous les outils sont différents, si vous utilisez la ligne de commande Git Bash, cette opération peut être effectuée en quelques étapes simples.

Tout d’abord, dans le dépôt, vous devez indexer tous vos changements en préparation du prochain commit. Vous pouvez le faire en exécutant :

git add --all

Ensuite, vous devez commiter vos changements enregistrés dans votre dépôt local. Vous pouvez le faire dans Git Bash en exécutant :

git commit -m "Short Description of Changes Made"

Enfin, étant donné que vous avez créé cette branche sur votre ordinateur local, vous devez le faire savoir à la duplication (fork) de votre compte GitHub.com. Si vous utilisez Git Bash, vous pouvez procéder en exécutant :

git push --set-upstream origin <branchname>

Bravo ! Votre code est maintenant dans votre dépôt GitHub et prêt pour vous permettre de créer une demande de tirage.

Conseil

Même si vos changements sont visibles dans votre compte GitHub personnel lorsque vous les envoyez (push), aucune règle n’est nécessaire pour envoyer tout de suite une demande de tirage. Si vous voulez arrêter et revenir plus tard pour faire des ajustements supplémentaires, c’est ok!

Vous devez corriger quelque chose que vous avez envoyé ? Aucun problème non plus ! Apportez simplement vos changements dans la même branche, puis commitez-les et envoyez-les à nouveau (inutile de définir le serveur en amont lors des pushs successifs de la même branche).

Modification suivante

Vous avez d’autres changements à apporter qui n’ont pas de rapport avec ceux-ci ? Revenez à la branche par défaut, puis effectuez un tirage (pull) à partir du dépôt en amont pour que votre duplication (fork) soit bien à jour. Enfin, extrayez une nouvelle branche. Exécutez les commandes suivantes dans Git Bash :

git checkout main
git pull upstream main
git checkout -b "branchname"

Notes

Les commandes précédentes supposent que le dépôt avec lequel vous travaillez utilise main comme branche par défaut. Si la première commande échoue, il est probable que la branche par défaut n’ait pas été renommée. Remplacez main dans les deux premières commandes par master pour le vérifier.

Vous êtes maintenant dans une nouvelle branche et vous voilà très bien parti pour devenir un expert en contribution.

Traitement des demandes de tirage (pull request)

La section précédente a décrit le processus d’envoi des modifications proposées, en les regroupant dans une nouvelle demande de tirage qui est ajoutée à la file d’attente des demandes de tirage du dépôt cible. Une demande de tirage active le modèle de collaboration de GitHub en demandant que les modifications de votre branche de travail soient tirées (pull) et fusionnées dans une autre branche. Dans la plupart des cas, cette autre branche est la branche par défaut du dépôt principal.

Validation

Avant de pouvoir fusionner votre demande de tirage dans sa branche de destination, vous devrez probablement effectuer une ou plusieurs procédures de validation. Les procédures de validation peuvent varier en fonction de l’étendue des modifications proposées et des règles du dépôt cible. Après l’envoi de votre demande de tirage, un ou plusieurs des événements suivants peuvent se produire :

  • Fusionnabilité : Un test de fusionnabilité GitHub de référence est d’abord effectué pour vérifier si les modifications proposées dans votre branche ne sont pas en conflit avec la branche de destination. Si la demande de tirage indique que ce test a échoué, vous devez réconcilier le contenu qui provoque le conflit de fusion pour que le traitement puisse continuer.
  • Contrat de licence de contribution (CLA) : Si vous contribuez à un dépôt public et que vous n’êtes pas un employé Microsoft, en fonction de l’importance des modifications proposées, il vous sera probablement demandé de remplir un contrat de licence de contribution la première fois que vous envoyez une demande de tirage à ce dépôt. Une fois le contrat SLA rempli, votre demande de tirage est traitée.
  • Étiquetage : Des étiquettes sont appliquées automatiquement à votre demande de tirage pour indiquer l’état de celle-ci au fur et à mesure qu’elle progresse dans le workflow de validation. Par exemple, les nouvelles demandes de tirage peuvent recevoir automatiquement l’étiquette « ne pas fusionner », indiquant que la demande de tirage n’a pas encore subi les étapes de validation, de revue et d’accord final.
  • Validation et génération : Des contrôles automatisés vérifient si vos modifications passent les tests de validation. Les tests de validation peuvent générer des avertissements ou des erreurs, qui vous obligent à apporter des modifications à un ou plusieurs fichiers de votre demande de tirage pour permettre à celle-ci d’être fusionnée. Les résultats des tests de validation sont ajoutés sous forme de commentaires à votre demande de tirage pour être utilisés lors de votre revue et peuvent vous être envoyés dans un e-mail.
  • Préproduction : Les pages de l’article affectées par vos modifications sont déployées automatiquement sur un environnement de préproduction pour revue, en attendant que la validation et la génération réussissent. Des URL de préversion apparaissent dans un commentaire de demande de tirage.
  • Fusion automatique : La demande de tirage peut être fusionnée automatiquement si elle passe les tests de validation et répond à certains critères. Dans ce cas, vous n’avez aucune autre action à effectuer.

Revue et accord final

Une fois le traitement de la demande de tirage terminé, vous devez examiner les résultats (commentaires de la demande de tirage, URL des préversions, etc.) pour déterminer si des modifications supplémentaires de ses fichiers sont nécessaires avant de marquer votre accord final pour la fusion. Si un réviseur de demande de tirage a revu votre demande de tirage, il peut avoir indiqué via des commentaires si des problèmes ou des questions en suspens doivent être résolus avant la fusion.

L’automatisation des commentaires permet aux utilisateurs de niveau lecture (utilisateurs qui ne disposent pas d’autorisations d’écriture dans un dépôt) d’effectuer une action au niveau de l’écriture, en affectant l’étiquette appropriée à une demande de tirage (PR). Si vous travaillez dans un dépôt où l’automatisation des commentaires a été implémentée, utilisez les commentaires de hashtag répertoriés dans le tableau suivant pour attribuer des étiquettes, modifier des étiquettes ou fermer une demande de tirage. Les employés de Microsoft seront également avertis par e-mail de la révision et la validation des demandes de tirage de dépôt public, chaque fois que des modifications sont proposées pour des articles dont vous êtes l’auteur.

Commentaire de hashtag Résultat Disponibilité du dépôt
#sign-off Affecte automatiquement l’étiquette prêt à fusionner pour informer les réviseurs du dépôt que la demande de tirage est prête pour révision/fusion.

Si vous n’êtes pas l’auteur répertorié et que vous essayez de signer une demande de tirage de dépôt public à l’aide du #sign-off commentaire, la demande de tirage est mise à jour pour indiquer que seul l’auteur peut attribuer l’étiquette.		 Publics et privés
#hold-off Supprime l’étiquette prête à fusionner au cas où vous changez d’avis ou que vous faites une erreur. Dans le dépôt privé, le libellé do-not-merge (ne pas fusionner) est affecté. Publics et privés
#please-close Ferme la demande de tirage si vous décidez de ne pas fusionner les modifications. Publics et privés
#please-open Rouvre une demande de tirage ou un problème fermé. Publics et privés
#label:"custom label text" Ajoute une étiquette personnalisée jusqu’à 200 caractères (plus courte recommandée). Publics et privés
#assign:<GitHub account> Ajoute un compte GitHub aux personnes assignées dans la demande de tirage ou le problème. Le compte doit être un contributeur valide dans le dépôt. Publics et privés
#reassign:<Github account> Supprime tous les assignés actuels et ajoute un compte GitHub aux personnes assignées dans la demande de tirage ou le problème. Le compte doit être un contributeur valide dans le dépôt. Publics et privés
#assign-reviewer:<GitHub account> Ajoute un compte GitHub aux réviseurs dans la demande de tirage. Le compte doit être un contributeur valide dans le dépôt. Publics et privés
#unassign-reviewer:<GitHub account> Supprime un compte GitHub des réviseurs dans la demande de tirage. Publics et privés

Si la demande de tirage n’a plus de problème et a reçu un accord final, vos modifications sont fusionnées dans la branche parent et la demande de tirage est clôturée.

Publication

Rappelez-vous que votre demande de tirage doit être fusionnée par un réviseur de demande de tirage pour que les modifications puissent être incluses dans la publication planifiée suivante. Les demandes de tirage sont normalement revues/fusionnées dans leur ordre d’envoi. Si votre demande de tirage doit être fusionnée pour une publication spécifique, vous devez travailler avec votre réviseur de demande de tirage suffisamment à l’avance pour que la fusion soit effectuée avant la publication.

Une fois vos contributions approuvées et fusionnées, elles sont collectées par le processus de publication. En fonction de l’équipe qui gère le dépôt auquel vous contribuez, le délai de publication peut varier. Les articles publiés dans les emplacements suivants sont normalement déployés aux environs de 10h30 et 15h30 (heure du Pacifique, GMT-8), du lundi au vendredi :

Jusqu’à 45 minutes peuvent être nécessaires pour que les articles apparaissent en ligne après la publication. Une fois votre article publié, vous pouvez vérifier vos modifications à l’URL appropriée : https://learn.microsoft.com/<path-to-your-article-without-the-md-extension>.

Étapes suivantes

Et voilà ! Vous avez apporté une contribution au contenu Microsoft Learn !