Bases de Git et GitHub pour la documentation Microsoft Learn

  • Article

Vue d’ensemble

En tant que contributeur à la documentation de Microsoft Learn, vous serez amené à 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 de dépôts Git, comme ceux utilisés pour stocker le contenu de 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.

Cet article définit les termes clés qui font partie du workflow de Microsoft Learn. Il fournit également un aperçu des référentiels Git et GitHub, et explique comment le contenu est organisé pour la documentation technique de Microsoft.

Branche

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.

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 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.

Tous les référentiels contiennent une branche par défaut (généralement nommée « main ») et une ou plusieurs branches en cours de réalisation qui n'ont pas encore été intégré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.

Chaque fois que 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. Nous ne déconseillons d'apporter des modifications directement dans la branche par défaut.

Duplication (fork)

Ce terme est normalement utilisé comme un nom lorsqu'il fait référence à une copie d'un référentiel GitHub principal. En pratique, un embranchement 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é comme un verbe, comme lorsque l'on dit « Vous devez d'abord dupliquer (fork) le référentiel ».

Git

Si vous êtes familier avec les systèmes de contrôle de version centralisés (tels que Team Foundation Server, SharePoint ou Visual SourceSafe), vous remarquerez que Git a un workflow de contribution unique et une terminologie pour soutenir son modèle distribué. Par exemple, il n'y a pas de verrouillage de fichier normalement associé aux opérations de check-out/check-in. Au lieu de cela, Git se préoccupe des changements à un niveau encore plus détaillé, 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 référentiel contient une ou plusieurs branches.
  • Branche : unité de stockage qui contient les fichiers et dossiers qui composent le jeu de contenu d’un projet. Pour plus d'informations sur les branches, veuillez consulter la section Branche de cet article.

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

Remarque

Même si les instructions relatives à la documentation sont basées sur l’utilisation de GitHub, certaines équipes utilisent Visual Studio Team Services pour héberger les 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. Elles peuvent être requises dans certains dépôts Microsoft Learn.

Tous les flux de travail commencent et se terminent au niveau de GitHub, où est stocké le dépôt principal de tout projet de documentation. 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

La branche par défaut d'un projet sert de version actuelle du contenu pour le projet. Le contenu de la branche par défaut (et les branches créées à partir de celle-ci) est approximativement aligné sur l’organisation des articles dans les pages Microsoft Learn correspondantes. Les sous-répertoires sont utilisés pour séparer les articles similaires (tels que les services), le contenu multimédia (tel que les fichiers d'images), et les fichiers « include » (qui permettent la réutilisation du contenu).

Sous-répertoire des articles

Vous trouverez généralement un répertoire articles principal à la racine du dépôt. Le répertoire articles contient un ensemble de sous-répertoires. Les articles dans les sous-répertoires sont formatés en fichiers Markdown qui utilisent une 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. Le 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.

Origine

Ce terme est le nom attribué à la connexion entre votre référentiel local et le référentiel à partir duquel il a été cloné. Dans le workflow de Microsoft Learn, l'origine représente la connexion à votre duplication (fork). Ce terme est parfois utilisé comme un surnom pour le dépôt d'origine lui-même, comme lorsque l'on dit « N'oubliez pas d'envoyer (push) vos changements vers l'origine ».

Requêtes de tirage

Une demande de tirage (pull request) (PR) est une demande faite au propriétaire du contenu pour intégrer vos changements dans la source officielle. Une PR permet le modèle de collaboration de GitHub en demandant un tirage des changements (également connus sous le nom de commits) sur votre branche branches en cours de réalisation et qu ces derniers soient fusionnés dans une autre branche. Dans la plupart des cas, cette autre branche est la branche par défaut du dépôt principal.

Une PR sert également de mécanisme pour fournir au contributeur des retours des processus de validation de Microsoft Learn et de l'évaluateur de la PR pour résoudre les problèmes ou les questions avant que les changements soient fusionnés dans la branche par défaut.

Remote

Un référentiel distant est une connexion nommée à un référentiel distant, comme le référentiel « origin » ou « upstream ». Git les appelle « remotes », car elles servent à faire référence à un dépôt hébergé sur un autre ordinateur. Dans le workflow de Microsoft Learn, un référentiel distant est toujours un dépôt GitHub.

En amont

Comme le référentiel distant d'origine, upstream est une connexion nommée à un autre référentiel. Dans le workflow de Microsoft Learn, l'amont représente la connexion entre votre référentiel local et le référentiel principal à partir duquel votre fork a été créée. Ce terme est parfois utilisé comme un surnom pour le référentiel amont lui-même, comme dans « N'oubliez pas d'effectuer le tirage (pull) des derniers changements de l'amont».

En savoir plus

Si vous ne connaissez pas encore Git ou GitHub, ces ressources peuvent vous aider à les découvrir, à gagner en productivité ou à répondre à certaines questions.

Ressources de contrôle de code source Git

Ressources GitHub

FAQ

Qu’est-ce que Git ?

Git permet de suivre les modifications quand de nombreuses personnes travaillent ensemble sur du code informatique. C’est comme une machine à remonter le temps pour le code. Vous pouvez donc voir ce qui a changé et revenir en arrière si nécessaire.

Pourquoi utiliser Git ?

C’est génial pour le travail en équipe. Git facilite le travail d’un grand nombre de personnes sur le même projet sans gâcher le travail de l’autre. Il permet également de corriger facilement les erreurs.

Comment fonctionne-t-il ?

Git stocke toutes les versions du code d’un projet. Quand vous apportez des modifications, Git prend une photo (comme un instantané) de ce qui est différent. Vous pouvez créer des versions différentes en même temps sans problème.

Que sont les branches dans Git?

Les branches sont similaires à des chemins d’accès différents dans un projet. Elles permettent aux gens de travailler sur de nouvelles choses sans changer le projet principal. Plus tard, ils peuvent ramener ces modifications dans le projet principal.

Qu’est-ce qu’une validation dans Git ?

Une validation est semblable à un point d’enregistrement. Il s’agit d’un moyen d’enregistrer les modifications que vous avez apportées. Chaque validation dispose d’un ID unique et une note sur ce qui a été modifié.

Qu’est-ce que GitHub ?

GitHub est un site web où vous pouvez stocker vos projets Git. C’est comme un grand hub pour partager et travailler ensemble sur le code avec d’autres personnes. Il permet également de suivre qui a changé quoi.

Comment GitHub diffère-t-il de Git ?

Git renvoie à l’outil de suivi des modifications, tandis que GitHub renvoie à l’endroit où stocker vos projets et travailler ensemble. GitHub utilise Git pour opérer sa magie.

GitHub est-il gratuit ?

Oui, pour les projets que tout le monde peut voir. Mais pour les projets privés (uniquement vous et votre équipe), vous devrez peut-être payer. Ils offrent différents plans avec des fonctionnalités supplémentaires.

Qu’est-ce que les demandes de tirage dans GitHub ?

Les demandes de tirage ressemblent à demander à placer vos modifications dans le projet principal. Des personnes pouvent passer en revue et discuter des modifications avant leur ajout.

Quelle est la sécurité de GitHub ?

GitHub prend bien soin de la sécurité. Ils utilisent des codes et des règles spéciaux pour s’assurer que seules les personnes adéquates peuvent accéder et modifier votre code. Vous pouvez également ajouter des couches de sécurité supplémentaires comme l’authentification à 2 facteurs pour plus de sécurité.