Bases de Git et GitHub pour la documentation Microsoft Learn

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 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 flux de travail Microsoft Learn. Il fournit également une vue d’ensemble des référentiels Git et GitHub, et explique comment le contenu est organisé pour la documentation technique 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 un branche par défaut (généralement nommé « main ») et une ou plusieurs branches de travail en cours (que nous appelons branches de travail) qui n’ont pas encore été intégrées au 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 vous déconseillons d’apporter des modifications directement au branche par défaut.

Duplication (fork)

Ce terme est normalement utilisé comme nom lors de la référence à une copie d’un dépôt 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 verbe, comme dans « Vous devez d’abord fourcher le référentiel ».

Git

Si vous connaissez bien les systèmes de contrôle de version centralisés (tels que Team Foundation Server, SharePoint ou Visual Source Coffre), vous remarquerez que Git dispose d’un flux de travail et d’une terminologie de contribution uniques pour prendre en charge son modèle distribué. Par exemple, aucun verrouillage de fichier n’est normalement associé aux opérations case activée-out/case activée-in. Au lieu de cela, Git s’inquiète des modifications à un niveau encore plus fin, comparant les octets d’octets de fichiers.

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, consultez 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

Le 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 des articles tels que des services, du contenu multimédia (tels que des fichiers image) et des fichiers « include » (qui permettent la réutilisation du contenu).

Sous-répertoire Articles

Vous trouverez généralement un répertoire articles principal à la racine du dépôt. / articles`` directory contains a set of subdirectories Articles in the subdirectories are formatted as Markdown files that use an *.md* extension. Some repositories that support multiple services use a generic articlessubdirectory, such as the [Azure-Docs](https://github.com/MicrosoftDocs/Azure-Docs) repository. Others might use a service-specific name, such as the [IntuneDocs](https://github.com/MicrosoftDocs/IntuneDocs) repository, which uses/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 flux de travail Microsoft Learn, l’origine représente la connexion à votre fourche. Ce terme est parfois utilisé comme moniker pour le référentiel d’origine lui-même, comme dans « N’oubliez pas d’envoyer vos modifications à l’origine ».

Requêtes de tirage

Une demande de tirage (pull request ) est une demande de propriétaire de contenu pour extraire vos modifications dans la source officielle. Une demande de tirage permet au modèle de collaboration de GitHub en demandant les modifications (également appelées validations) de votre branche de travail à extraire et à fusionner dans une autre branche. Dans la plupart des cas, cette autre branche est la branche par défaut du dépôt principal.

Une demande de tirage sert également de mécanisme pour fournir aux contributeur des commentaires des processus de validation de Microsoft Learn et du réviseur de demande de tirage, afin de résoudre les problèmes potentiels ou les questions avant que les modifications ne soient fusionnées dans le branche par défaut.

Remote

Une connexion distante est une connexion nommée à un dépôt distant, telle que l'« origine » ou « amont » distante. Git les appelle « remotes », car elles servent à faire référence à un dépôt hébergé sur un autre ordinateur. Dans le flux de travail Microsoft Learn, un dépôt GitHub distant est toujours un dépôt GitHub.

En amont

Comme l’origine distante, amont est une connexion nommée à un autre référentiel. Dans le flux de travail Microsoft Learn, le amont représente la connexion entre votre référentiel local et le référentiel principal à partir duquel votre fourche a été créée. Ce terme est parfois utilisé comme moniker pour le référentiel amont lui-même, comme dans « N’oubliez pas d’extraire les dernières modifications de la 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é.