Principes fondamentaux de la contribution pour Microsoft Learn
Certains termes vous aideront à comprendre et à terminer le processus de contribution. Il n’est pas nécessaire de savoir tout ce qui se passe en arrière-plan, mais une vue d’ensemble générale du fonctionnement de la contribution vous aide à comprendre pourquoi le processus fonctionne comme il le fait.
Notions de base sur Microsoft Learn et GitHub
Microsoft Learn contient des milliers d’articles, de modules de formation, de pages web, etc., qui doivent être stockés et auxquels différents contributeurs accèdent régulièrement. Microsoft Learn utilise GitHub pour stocker une grande partie de ce contenu. GitHub est une plateforme qui utilise Git, un système de contrôle de version distribué, pour stocker des projets et faciliter la collaboration entre plusieurs parties prenantes avec différents objectifs de projet et chronologies. Les logiciels Git et GitHub vous permettent de travailler en parallèle avec d’autres contributeurs sur le même projet, potentiellement sur exactement le même contenu, voire en même temps, sans interférer involontairement avec le travail d’autres personnes.
Le contenu est stocké dans des fichiers dans des référentiels Git hébergés sur GitHub. Un référentiel est une unité de stockage qui contient les fichiers et l’historique de révision des fichiers d’un projet. Les référentiels peuvent être publics ou privés, et Microsoft Learn est constitué d’un mélange des deux. N’importe qui peut contribuer à un référentiel public une fois qu’il a configuré un compte GitHub. Les référentiels privés ne sont disponibles que pour les contributeur qui sont des employés Microsoft ou qui ont reçu une autorisation spéciale.
Apporter des modifications au contenu Microsoft Learn stocké dans un référentiel GitHub
Pour n’importe quel projet, GitHub héberge le référentiel principal et toutes les duplications (fork). Une duplication est une copie du référentiel principal qu’un contributeur fait pour son propre travail. Une duplication (fork) est une des façons dans GitHub de protéger le contenu publié. Au lieu de modifier directement le contenu de la branche active et publiée du référentiel principal, GitHub prend un instantané de ce contenu pour votre duplication (fork) pour vous permettre d’y apporter vos modifications.
Les référentiels GitHub contiennent une ou plusieurs branches. Une branche est une unité de stockage qui contient les fichiers et dossiers qui composent le jeu de contenu d’un projet. Tous les référentiels, qu’il s’agisse du référentiel principal ou d’une duplication (fork), contiennent une branche par défaut (généralement nommée main), et une ou plusieurs branches destinées à être fusionnées dans la branche par défaut. La branche par défaut sert de version actuelle et de « seule source de vérité » pour le projet. Il s’agit du parent à partir duquel toutes les autres branches dans le dépôt sont créées.
La modification d’un article de documentation dans un référentiel public peut paraître commencer par l’utilisation d’un bouton, mais plusieurs choses se produisent en arrière-plan. Quand vous démarrez le processus de modification basé sur le navigateur, une duplication (fork) du référentiel est créée (si vous n’en avez pas déjà une) et utilisée pour vos modifications. Vous modifiez dans une branche de votre duplication, qui sera ensuite fusionnée vers la branche active du référentiel principal afin que vos modifications soient disponibles pour tous.
Créer une demande de tirage (pull request)
Comment cette fusion se produit-elle ? Vous devez indiquer à GitHub, plus spécifiquement aux propriétaires du référentiel principal et aux auteurs de l’article, que vos modifications sont finalisées, et prêtes pour la révision, la publication et l’exposition à la vue du monde entier ! Pour ce faire, vous créez et envoyez une demande de tirage.
Une demande de tirage (pull request) est une proposition pour que vos modifications soient fusionnées depuis la branche de votre duplication (fork) où vous avez travaillé vers la branche main par défaut du référentiel actif. Quand vous travaillez dans un référentiel public, vos demandes de tirage (pull request) sont toujours révisées par un réviseur humain avant d’être fusionnées. Il peut également y avoir des vérifications automatisées, comme la compatibilité de la fusion et la validation de la build. Une fois ces révisions terminées et tous les problèmes résolus, vos modifications sont fusionnées vers la branche active et deviennent disponibles sur Microsoft Learn !
Flux de travail pour les contributions mineures à la documentation
En résumé, vous allez suivre ces étapes générales lors de petites modifications apportées à la documentation Microsoft en utilisant l’éditeur web dans GitHub :
- Lorsque vous ouvrez un fichier dans votre navigateur pour le modifier, une duplication du référentiel public est automatiquement créée pour vous. Une branche dans votre duplication est également créée, souvent appelée branche correctifs (patch).
- Apportez vos modifications au fichier.
- Créez une demande de tirage pour proposer que vos modifications soient examinées et fusionnées.
- Votre demande de tirage doit résoudre tous les problèmes et passer toutes les révisions.
- Votre demande de tirage est fusionnée vers la branche principale du référentiel actif et vos modifications sont publiées sur Microsoft Learn.
Examinons ensuite chaque étape de plus près pour découvrir comment les réaliser.