Git et GitHub essentials for Microsoft Learn documentation

  • Article

Vue d’ensemble

En tant que contributeur à la documentation Microsoft Learn, vous allez interagir avec plusieurs outils et processus. Vous travaillez en parallèle avec d’autres contributeurs sur le même projet, peut-être exactement le même contenu, voire en même temps. Tout cela est possible avec les logiciels Git et GitHub.

Git est un système de gestion de versions open source. Il facilite ce type de collaboration sur les projets avec une gestion distribuée des versions des fichiers qui résident dans les dépôts. En substance, Git permet d’intégrer des flux de travail effectués par plusieurs contributeurs au fil du temps, pour un référentiel donné.

GitHub est un service d’hébergement web pour les dépôts Git, tels que ceux utilisés pour stocker du contenu Microsoft Learn . Pour un projet donné, GitHub héberge le dépôt principal, à partir duquel les contributeurs peuvent faire des copies pour leur propre travail.

Git

Si vous connaissez les systèmes de gestion de versions centralisés (comme Team Foundation Server, SharePoint ou Visual SourceSafe), vous remarquerez que Git a un flux de travail de contribution unique et une terminologie propre pour prendre en charge son modèle distribué. Par exemple, il n'y a pas le verrouillage de fichiers normalement associé aux opérations de verrouillage/déverrouillage. En fait, Git s’intéresse aux changements à un niveau encore plus fin, en comparant les fichiers octet par octet.

Git utilise également une structure hiérarchisée pour stocker et gérer le contenu d’un projet :

  • Dépôt : il s’agit de l’unité de stockage la plus haute. Un dépôt contient une ou plusieurs branches.
  • Branche : unité de stockage qui contient les fichiers et dossiers qui composent le jeu de contenu d’un projet. Les branches servent à séparer les flux de travail (généralement appelés « versions »). Les contributions sont toujours apportées et limitées à une branche spécifique. Tous les dépôts contiennent une branche par défaut (la branche « main ») et une ou plusieurs branches destinées à être à nouveau fusionnées avec 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.

Les contributeurs interagissent avec Git pour mettre à jour et manipuler des dépôts au niveau local et au niveau de GitHub :

  • Localement au moyen d’outils tels que la console Git Bash, qui prend en charge les commandes Git pour la gestion des dépôts locaux et la communication avec les dépôts GitHub.
  • Par l’intermédiaire de www.github.com, qui intègre Git pour gérer le rapprochement des contributions qui reviennent vers le dépôt principal.

GitHub

Notes

Bien que les conseils de documentation soient basés sur l’utilisation de GitHub, certaines équipes utilisent Visual Studio Team Services pour héberger des dépôts Git. Le client Visual Studio Team Explorer fournit une interface graphique utilisateur permettant d’interagir avec les dépôts Team Services, comme alternative à l’utilisation des commandes Git en ligne de commande.
De plus, nombre des instructions ci-dessous ont été élaborées pour servir de bonnes pratiques sur la base d’années d’expérience dans l’hébergement de contenu de service Azure dans GitHub. Ils peuvent être requis dans certains référentiels Microsoft Learn.

Tous les flux de travail commencent et se terminent au niveau GitHub, où le dépôt main pour n’importe quel projet de documentation est stocké. Les contributeurs créent des copies pour leur propre utilisation, qui sont réparties sur plusieurs ordinateurs. Elles sont finalement réintégrées plus tard dans le dépôt GitHub principal du projet.

Organisation des répertoires

Comme évoqué précédemment, une branche de projet par défaut sert de version actuelle du contenu pour le projet. Le contenu du branche par défaut(et des branches créées à partir de celui-ci) est légèrement aligné sur la organization des articles des pages Microsoft Learn correspondantes. Les sous-répertoires sont utilisés pour la séparation du contenu similaire (comme les services), du contenu multimédia (comme les fichiers image) et les fichiers « include » qui permettent la réutilisation du contenu.

Vous trouverez généralement un répertoire articles principal à la racine du dépôt. Il contient un ensemble de sous-répertoires. Les articles des sous-répertoires sont au format Markdown, avec l’extension .md. Certains dépôts qui prennent en charge plusieurs services utilisent un sous-répertoire /articles générique, comme le dépôt Azure-Docs. D’autres peuvent utiliser un nom propre au service, comme le dépôt IntuneDocs, qui utilise /IntuneDocs.

Au sein de la racine de ce répertoire, vous pouvez trouver des articles généraux qui se rapportent au service ou produit global. Généralement, vous trouverez une autre série de sous-répertoires, qui correspondent aux fonctionnalités/services ou à des scénarios courants. Par exemple, les articles Azure « machine virtuelle » se trouvent dans le sous-répertoire /virtual-machines et les articles Intune « comprendre et explorer » se trouvent dans le sous-répertoire /understand-explore.

Sous-répertoire multimédia

Chaque répertoire d’articles contient un sous-répertoire /media pour les fichiers multimédias associés. Ces fichiers incluent des images utilisées par des articles avec des références d’images.

Sous-répertoire d'includes

Chaque fois que du contenu réutilisable est partagé entre plusieurs articles, il est placé dans un sous-répertoire /includes du répertoire articles principal. Dans un fichier Markdown qui utilise le fichier include, une extension Markdown include correspondante est placée là où le fichier include doit être référencé.

Consultez Référence du Markdown : Includes pour des instructions supplémentaires.

Modèle de fichier Markdown

Par souci pratique, le répertoire racine de chaque dépôt contient généralement un fichier modèle Markdown appelé template.md. Vous pouvez l’utiliser comme « fichier de démarrage » si vous devez créer un article et l’envoyer au dépôt. Ce fichier contient :

  • Un en-tête de métadonnées en haut du fichier, délimité par deux lignes constituées de 3 traits d’union. Il contient les différentes balises utilisées pour le suivi des informations relatives à l’article. Les métadonnées d’articles activent certaines fonctionnalités, telles que l’attribution de l’auteur, l’attribution du contributeur, les vues miniatures et les descriptions des articles. Elles comprennent aussi les optimisations du référencement d’un site auprès d’un moteur de recherche, ainsi que la création de rapports sur les processus utilisés par Microsoft pour évaluer les performances du contenu. Les métadonnées sont donc très importantes.
  • Une section des métadonnées qui décrit les balises et les valeurs des métadonnées. Si vous ne connaissez pas les valeurs à utiliser pour la section des métadonnées, vous pouvez la laisser vide ou insérer un commentaire commençant par un hashtag (#). Il sera révisé ou complété par le réviseur de la demande de tirage du dépôt.
  • Plusieurs exemples d’utilisation de fichiers Markdown pour mettre en forme les éléments d’un article.
  • Des instructions générales sur l’utilisation des extensions Markdown, qui peuvent être utilisées pour différents types d’alertes.
  • Des exemples d’intégration de la vidéo à l’aide d’un iframe.
  • Des instructions générales sur l’utilisation des extensions de la documentation technique de Microsoft, qui peuvent être utilisées pour des contrôles spéciaux, tels que des boutons ou des sélecteurs.

Demandes de tirage

Une demande de tirage (pull request) offre un moyen pratique à un contributeur de proposer un ensemble de modifications à appliquer à la branche par défaut. Les modifications (aussi appelées validations) sont stockées dans la branche d’un contributeur, ce qui permet à GitHub de commencer par modéliser l’impact de leur fusion dans la branche par défaut. Une requête de tirage sert également de mécanisme pour fournir au contributeur des commentaires lors d'un processus de génération/validation, par l'examinateur des requêtes de tirage, pour résoudre les éventuels problèmes ou questions avant la fusion des modifications avec la branche par défaut.

Il existe deux méthodes de contribution par demande de tirage, selon la taille des modifications suggérées. Nous aborderons tout cela en détail plus tard, dans la section Flux de travail de GitHub de ce guide.