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

Important

Tous les référentiels qui publient dans Microsoft Docs ont adopté le Code de conduite open source de Microsoft 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 corrections mineures ou les clarifications pour la documentation, ainsi que les exemples de code dans les référentiels publics, sont couverts par les Conditions d’utilisation du site web docs.microsoft.com. 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 vous arrêter et revenir ultérieurement pour effectuer d’autres ajustements, aucun problème !

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 de commentaires permet aux utilisateurs en lecture (les utilisateurs ne disposant pas d’autorisations en écriture dans un dépôt) d’effectuer une action en écriture, en affectant le libellé approprié à une demande de tirage. Si vous travaillez dans un dépôt où l’automatisation de commentaires a été implémentée, utilisez les commentaires de hashtag répertoriés dans le tableau suivant pour affecter des libellés, modifier les libellés 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 Quand l’auteur d’un article tape le commentaire #sign-off dans le flux de commentaires, le libellé prêt pour la fusion est affecté. Ce libellé informe les réviseurs dans le dépôt quand une demande de tirage est prête pour la révision/fusion.

Si un contributeur qui n’est pas l’auteur listé tente de valider une demande de tirage de dépôt public à l’aide du commentaire #sign-off, un message est écrit dans la demande de tirage qui indique que seul l’auteur peut affecter le libellé.
Publics et privés
#hold-off Les auteurs peuvent taper #hold-off dans un commentaire de demande de tirage pour supprimer le libellé prêt pour la fusion, au cas où ils changeraient d’avis ou feraient une erreur. Dans le dépôt privé, le libellé do-not-merge (ne pas fusionner) est affecté. Publics et privés
#please-close Les auteurs peuvent taper #please-close dans le flux de commentaires pour fermer la demande de tirage s’ils décident de ne pas fusionner les modifications. Public

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 de Microsoft Docs !