Principes fondamentaux de la contribution pour Microsoft Learn

Effectué

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. Git et le logiciel GitHub vous permettent de travailler en parallèle avec d’autres contributeurs sur le même projet, potentiellement le même contenu, ou 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 d’un projet et l’historique de révision des fichiers. 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 est l’une des façons de protéger le contenu publié par GitHub. Au lieu de modifier directement le contenu dans la branche active et publiée du référentiel principal, GitHub prend une capture instantanée de ce contenu pour votre duplication, afin de pouvoir 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, contiennent une branche par défaut (généralement nommée « principale ») 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.

Diagram showing a working branch off of the main branch in a GitHub repo. Changes are made in the working branch then merged back to main.

La modification d’un article de documentation dans un référentiel public peut sembler comme si elle commençait par le toucher d’un bouton, mais plusieurs choses se produisent en arrière-plan. Lorsque vous démarrez le processus d’édition basé sur le navigateur, une duplication 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 , en particulier aux propriétaires du référentiel principal et aux auteurs de l’article, que vos modifications sont finalisées et prêtes à être examinées et publiées à la vue de tout le monde ! 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 à partir de la branche de votre duplication dans laquelle vous travailliez vers la branche « principale » par défaut du référentiel actif. Lorsque vous travaillez dans un référentiel public, vos demandes de tirage sont toujours examinées par un réviseur humain avant d’être fusionnées. Il peut également y avoir des vérifications automatisées, telles que la compatibilité de fusion et la validation de build. Une fois ces révisions terminées et tous les problèmes résolus, vos modifications seront fusionnées vers la branche active et seront 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 à l’aide de l’éditeur web dans GitHub :

Diagram of the contribution process for contributing to open source documentation on Microsoft Learn.

  1. 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).
  2. Apportez vos modifications au fichier.
  3. Créez une demande de tirage pour proposer que vos modifications soient examinées et fusionnées.
  4. Votre demande de tirage doit résoudre tous les problèmes et passer toutes les révisions.
  5. 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 apprendre à les réaliser.