Apporter des modifications importantes à la documentation Microsoft Learn

Article
01/28/2024

Important

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

Les corrections mineures et clarifications de la documentation ainsi que les exemples de code des dépôts publics sont couverts par les conditions d’utilisation du site learn.microsoft.com. Toute modification génère un commentaire dans la demande de tirage (pull request) qui vous invite à signer un contrat de licence de contribution en ligne (CLA) si vous n’êtes pas un employé de Microsoft. Vous devrez remplir le formulaire en ligne pour que nous puissions accepter votre demande de tirage.

Cet article décrit comment modifier un article Microsoft Learn à l’aide d’outils locaux. Il 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 font généralement des changements durables (à long terme) qui passent par plusieurs cycles de création/validation/indexation ou qui sont 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, vos contributions (ajouts, modifications ou suppressions) qui englobent plusieurs articles et qui doivent être commité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’éditeur web de GitHub et attendez avant de pouvoir commiter vos modifications.
Mise à jour continue du même article après l’ouverture d’une demande de tirage. Bien que vous puissiez utiliser l’éditeur web de GitHub à cet effet, vous pouvez créer plusieurs demandes de tirage en attente pour le même fichier, ce qui peut générer des conflits.

Prérequis

Identifiez le dépôt GitHub qui stocke la documentation que vous souhaitez modifier.
Créez un compte GitHub si vous n’en avez pas déjà un.
Installez les outils Git et Markdown.
Configurez un dépôt Git local.
Consultez les notions de base de Git et de GitHub (facultatif).

Créer et extraire votre branche de travail

Pour commencer, créez une branche de travail dans votre référentiel local pour capturer vos modifications proposées. Pour plus d’informations sur les branches, consultez les notions de base de Git et GitHub.

Ce tutoriel utilise Git Bash et Visual Studio Code, mais vous pouvez utiliser n’importe quels client et éditeur Git.

Dans VS Code, ouvrez le dossier qui contient le clone local du dépôt. Dans le menu Fichier , sélectionnez Ouvrir un dossier et accédez au dossier sur votre ordinateur.
Sélectionnez Affichage dans le menu supérieur, puis sélectionnez Terminal pour ouvrir le terminal intégré.
Dans le terminal intégré, vérifiez que vous êtes dans le dossier du dépôt.
Avant de créer une branche de travail, vérifiez que votre branche primaire locale contient bien tout ce qui se trouve dans la branche primaire du dépôt de production. Cette vérification garantit que votre branche de travail reflète toutes les modifications qui ont été apportées au dépôt de production depuis la dernière synchronisation.
1. Basculez vers la branche primaire de votre dépôt local :
```
git checkout main 
```
2. Vérifiez que votre branche primaire locale est à jour :
```
git pull upstream main 
```
Créez une branche de travail locale basée sur la branche primaire :
```
git checkout -b <branch-name>
```
<branch-name> est un espace réservé. Lorsque vous exécutez la commande, remplacez-le par un nom unique et explicite pour votre branche et supprimez les crochets.
Envoyez (push) la branche de travail locale à la branche distante dans votre duplication GitHub :
```
git push origin <branch-name> -u
```
L’option -u lie les branches locales et distantes. Elle vous permet d’envoyer (push) des commits vers votre duplication en entrant simplement git push au lieu de git push origin <branch-name>.

Rechercher le fichier Markdown source

Pour modifier un article, vous devez trouver son fichier source dans votre clone local du dépôt. Dans VS Code, accédez aux fichiers Markdown du référentiel via l’Explorateur de fichiers (icône de document dans la barre latérale supérieure gauche). La structure de dossiers du dépôt s’affiche. Vous pouvez alors accéder au fichier que vous souhaitez modifier.

Si vous ne le trouvez pas, accédez à l’article sur Microsoft Learn et sélectionnez l’icône Modifier en forme de crayon. L’emplacement relatif du dossier dans le dépôt GitHub est affiché dans l’URL. Voici un exemple d’URL d’un lien Modifier :

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Voici un exemple d’emplacement de fichier pour cette URL :

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Modifier le fichier

Sélectionnez le fichier pour l’ouvrir dans VS Code.
Effectuez vos modifications.
Enregistrez les changements apportés en sélectionnant Fichier>Enregistrer. Utilisez Enregistrer tout pour enregistrer plusieurs fichiers à la fois.

Commiter et envoyer (push) vos changements

Si vous avez apporté des modifications importantes ou révisé un article en vue de l’actualiser, mettez à jour ms.date dans le bloc de métadonnées en haut du fichier. Le format de date est le suivant : MM/JJ/AAAA.

Vous pouvez utiliser le terminal ou l’interface utilisateur de VS Code pour commiter et envoyer (push) vos modifications.

Terminal de VS Code
Interface utilisateur de VS Code

Exécutez la commande git status pour vérifier que seuls les fichiers que vous avez modifiés apparaissent dans la liste.
```
git status
```
Exécutez la commande git add suivie du chemin d’accès du fichier et de son nom pour indexer le fichier que vous avez modifié.
```
git add folder-name/file-name.md
```
Si vous avez modifié plusieurs fichiers, exécutez une commande git add pour chaque fichier.

Vous pouvez également exécuter git add . (notez le point après add) pour indexer automatiquement toutes les modifications que vous avez apportées. Cette méthode est plus rapide, mais peut entraîner des problèmes en incluant les modifications que vous avez apportées par accident.
Exécutez à nouveau git status pour confirmer que les modifications ont bien été indexées.
Exécutez la commande git commit suivie d’un message de commit pour enregistrer les modifications dans votre dépôt cloné en local.
```
git commit -m "your commit message"
```
Exécutez git push pour envoyer (push) vos modifications.
```
git push
```

Vous pouvez créer et envoyer (push) un commit à l’aide des fonctionnalités d’intégration Git de VS Code. N’oubliez pas de continuer votre travail sur le même ordinateur. Si vous en changez, vous n’aurez pas la dernière version de la branche de travail.

Assurez-vous que votre dépôt local dispose toujours de la même branche de travail. Dans l’interface utilisateur de VS Code, la branche est affichée dans le coin inférieur gauche. Les noms de branche servent également de boutons pour basculer de l’une à l’autre.
Dans la barre latérale gauche de VS Code, sélectionnez l’outil de duplication (fork) pour afficher le volet Contrôle de code source : Git.

Le fichier que vous avez modifié apparaît sous Modifications avec un M à droite pour indiquer qu’il a été modifié. Les nouveaux fichiers apparaissent avec un U (« untracked », non suivi) et les fichiers supprimés apparaissent avec un D (« deleted »).
Indexez les modifications. Passez la souris sur la ligne Modifications jusqu’à ce qu’une icône + s’affiche. Sélectionnez-la. Cette action est équivalente à la commande git add. Le fichier apparaît maintenant dans la section Changements indexés.
Entrez un message de commit tel que « mise à jour de la date des métadonnées » dans la zone de texte Message, puis cochez la case.
Envoyez (push) le commit. Utilisez le bouton Synchroniser les modifications qui apparaît sous le bloc de message du commit.

Bravo ! Votre code est maintenant dans votre dépôt GitHub. Vous pouvez maintenant créer une demande de tirage.

Vous devez corriger quelque chose que vous avez envoyé ? C’est facile. Il vous suffit de reprendre les étapes ci-dessus à partir de la section Modifier le fichier. 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 envois successifs de la même branche). En règle générale, les branches sont utilisées pour séparer les flux de travail. Vous n’avez donc pas besoin d’en créer une nouvelle, sauf si vous souhaitez travailler sur autre chose.

Passer à la modification suivante

Vous souhaitez apporter une autre modification, sans rapport avec la précédente ? Revenez à la branche par défaut, puis effectuez un tirage (pull) à partir du dépôt en amont pour que votre duplication 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"
git push origin <branch-name> -u

Vous êtes maintenant dans une nouvelle branche liée à votre branche distante, et vous pouvez apporter d’autres modifications. Vous êtes sur la bonne voie pour devenir un contributeur expert !

Étapes suivantes

Si vous avez suivi les étapes ci-dessus, il est temps d’ouvrir une demande de tirage pour que vos modifications soient fusionnées avec la branche primaire.
Pour plus d’informations sur des sujets, comme Markdown et la syntaxe des extensions Markdown, lisez l’article Informations de référence sur Markdown.