Passer au contenu principal
Git est un système de contrôle de version qui suit les modifications apportées à votre documentation et permet la collaboration en équipe. Avec Git, vous pouvez voir ce qui a changé au fil du temps dans les fichiers, qui a effectué les modifications, quand elles ont été faites et pourquoi. Git facilite également le retour à des versions précédentes de fichiers si vous devez annuler des modifications. L’éditeur web effectue des opérations Git en arrière-plan. En comprenant Git, vous pouvez travailler plus efficacement avec l’éditeur web et collaborer avec des membres de l’équipe qui utilisent un environnement de développement local.

​
Pourquoi utiliser Git pour la documentation ?

Git fournit des fonctionnalités essentielles pour gérer la documentation.
  • Historique des versions : Voir ce qui a changé, quand et pourquoi, pour chaque fichier.
  • Collaboration : Plusieurs personnes peuvent travailler sur différentes parties en parallèle.
  • Sécurité : Tester des changements sans risquer d’altérer la documentation en production.
  • Processus de revue : Les membres de l’équipe peuvent relire les changements avant la publication.
  • Récupération : Annuler des erreurs ou restaurer des versions précédentes.

​
Nouveau sur Git ?

Si vous découvrez totalement Git et le contrôle de version, voici un parcours pour vous lancer.
1

Utilisez d'abord l'éditeur web.

L’éditeur web gère automatiquement les opérations Git.
  • Visualisez immédiatement toutes les modifications au fur et à mesure.
  • Créez des branches en un clic.
  • Publiez et créez des pull requests (demandes de fusion) sans utiliser de commandes Git.
Cela vous permet d’apprendre les concepts de Git sans utiliser la ligne de commande.
2

Apprenez en pratiquant.

Lorsque vous utilisez l’éditeur web, vous utilisez Git.
  • Enregistrer les modifications crée un commit.
  • Créer une branche crée une branche Git.
  • Publier ouvre une pull request (demande de fusion) pour relecture.
3

Explorez le développement local lorsque c'est utile.

Vous pouvez gérer votre documentation entièrement avec l’éditeur web et le Dashboard, mais vous pouvez personnaliser votre flux de travail en travaillant dans votre environnement local.
  • Créez et modifiez des fichiers dans votre éditeur préféré.
  • Utilisez Git en ligne de commande, GitHub Desktop ou une extension dans votre éditeur.
  • Prévisualisez les modifications en local avant de les publier.
  • Intégrez d’autres outils comme les tickets de support, le suivi des problèmes et les design systems.

​
Concepts fondamentaux de Git

Une branche pointe vers un commit spécifique dans votre référentiel. Votre documentation en production est générée à partir d’une branche de déploiement. Vous pouvez avoir autant d’autres branches que vous voulez, contenant des modifications qui ne sont pas encore publiées dans votre documentation en production. Si vous voulez intégrer les modifications d’une branche dans votre documentation en production, vous pouvez fusionner la branche dans votre branche de déploiement via une pull request (demande de fusion).Utilisez les branches pour travailler sur des modifications sans affecter votre documentation en production, expérimenter en toute sécurité de nouvelles fonctionnalités et obtenir des revues avant la publication.
Téléchargez une copie complète d’un référentiel sur votre ordinateur, incluant tous les fichiers et l’historique complet. Lorsque vous clonez, vous obtenez tout ce dont vous avez besoin pour travailler en local.
git clone https://github.com/your-org/your-repo
Un instantané enregistré de vos modifications à un moment donné. Chaque commit inclut un message décrivant ce qui a changé et crée une trace permanente dans l’historique de votre projet.
Se produit lorsque deux personnes modifient différemment la même partie d’un fichier. Git vous demande de choisir manuellement quelle modification conserver ou de combiner les deux.
La branche principale de votre projet. Les modifications apportées à cette branche sont automatiquement publiées sur votre site de documentation. Souvent appelée main, mais vous pouvez définir n’importe quelle branche comme votre branche de déploiement.
Un diff (ou différence) montre les modifications entre deux versions d’un fichier. Lors de l’examen de pull requests (demandes de fusion), les diffs mettent en évidence ce qui est différent par rapport à la version d’origine du fichier.
Combinez les modifications d’une branche dans une autre. Généralement effectué via une pull request (demande de fusion) après revue pour intégrer un travail sur des fonctionnalités dans votre branche de déploiement.
Récupérez les dernières modifications depuis le référentiel distant vers votre copie locale. Vous permet de rester à jour avec le travail des autres.
git pull
Un moyen de proposer la fusion des modifications d’une branche dans votre documentation en production. Permet la revue et la discussion avant que les modifications ne soient mises en ligne. Couramment appelée PR, et aussi appelée merge request dans GitLab.
Envoyez vos commits locaux vers le référentiel distant. Cela rend vos modifications disponibles pour les autres et peut déclencher des déploiements automatiques.
git push
Une version de votre référentiel hébergée sur un serveur. Votre référentiel local se connecte à un référentiel distant pour pousser et récupérer des modifications.
Le code source de votre documentation, avec tous les fichiers et leur historique, qui composent les pages de votre site de documentation. L’éditeur en ligne se connecte à votre référentiel de documentation pour accéder au contenu et le modifier.
Préparez des modifications spécifiques à inclure dans votre prochain commit. Le staging vous permet d’organiser les modifications en commits logiques.
git add filename.mdx

​
Comment l’éditeur web utilise Git

L’éditeur web se connecte à votre référentiel Git via la GitHub App ou l’intégration GitLab et automatise les opérations Git courantes. Lorsque vous :
  • Ouvrez un fichier : l’éditeur récupère la dernière version depuis votre référentiel, pour que vous travailliez toujours avec un contenu à jour.
  • Apportez des modifications : l’éditeur suit vos modifications comme un brouillon, qui pourra devenir un commit lorsque vous serez prêt à enregistrer votre travail.
  • Enregistrez les modifications : l’éditeur crée un commit avec vos modifications, conservant votre travail dans l’historique du projet.
  • Créez une branche : l’éditeur crée une nouvelle branche dans votre référentiel, utilisable par toute personne ayant accès au référentiel afin de collaborer et de passer les changements en revue.
  • Publiez sur votre branche de déploiement : l’éditeur crée un commit et pousse directement vers votre branche de déploiement, ce qui publie immédiatement vos modifications.
  • Publiez sur d’autres branches : l’éditeur crée une pull request (demande de fusion), vous permettant d’obtenir des retours avant de fusionner vos modifications dans votre branche de déploiement.

​
Flux de travail courants

​
Publier directement dans votre branche de déploiement

  1. Ouvrez le fichier dans l’éditeur web.
  2. Apportez vos modifications.
  3. Cliquez sur Publish.
  4. Les modifications apparaissent dans le référentiel et sont déployées automatiquement.

​
Travailler sur une branche de fonctionnalité

Pour créer des pull requests (demandes de fusion) depuis l’éditeur web, vous devez avoir activé une règle de protection de branche qui impose des pull requests avant que les modifications puissent être fusionnées dans votre branche de déploiement. Sans règles de protection de branche, les modifications apportées sur les branches sont fusionnées dans votre branche de déploiement lors de la publication.
  1. Créez une branche à partir du menu déroulant des branches dans la barre d’outils de l’éditeur.
  2. Apportez et enregistrez des modifications sur la branche.
  3. Cliquez sur Publish pour créer une pull request.
  4. Fusionnez la pull request lorsque vous êtes prêt.

​
Passer en revue les changements avant la publication

1

Créer une branche de fonctionnalité.

Travaillez sur vos modifications dans une branche distincte de votre branche de déploiement afin de pouvoir les partager et les passer en revue avant la publication.
2

Apporter vos modifications.

Modifiez les fichiers et créez des commits sur la branche de fonctionnalité.
3

Créer une pull request.

Créez une pull request (demande de fusion) pour proposer la fusion des changements de votre branche de fonctionnalité dans la branche de déploiement.
4

Passer en revue le diff.

Vérifiez vos changements. La pull request affiche, ligne par ligne, les différences par rapport à la version d’origine du fichier.
5

Recueillir les retours de l’équipe.

Les membres de l’équipe peuvent commenter des lignes spécifiques ou l’ensemble des changements. Apportez les modifications nécessaires et créez des commits sur la branche de fonctionnalité.
6

Fusionner après approbation.

Fusionnez la pull request pour publier les changements sur votre documentation en production.

​
Bonnes pratiques Git

Chaque équipe développe ses propres flux de travail et préférences, mais voici quelques bonnes pratiques générales pour commencer.
  • Rédigez des messages de commit descriptifs : Soyez précis sur ce qui a changé en utilisant un langage actif. Fix broken link in API docs est plus informatif que update page.
  • Utilisez des noms de branches explicites : Les noms de branches doivent expliquer l’objectif de la branche. Utilisez des noms parlants comme update-api-reference plutôt que des noms génériques comme temp ou my-branch.
  • Gardez les branches ciblées : Limitez les changements sur une branche à une tâche ou un projet spécifique. Cela facilite les revues de code et réduit les conflits.
  • Supprimez les branches après fusion : Supprimez les branches dont vous n’avez plus besoin pour garder votre référentiel bien organisé.
  • Pull avant de push : Faites toujours un pull des dernières modifications avant de pousser pour éviter les conflits. L’éditeur web le fait automatiquement.
  • Relisez d’abord vos propres changements : Vérifiez le diff avant de créer une pull request (demande de fusion).