Travailler avec des branches

Créez des branches pour prévisualiser les modifications et collaborer avant la publication.

Les branches sont une fonctionnalité de gestion de versions qui pointent vers des commits spécifiques dans votre référentiel. Votre branche de déploiement, généralement appelée main, représente le contenu utilisé pour générer votre site de documentation en ligne. Toutes les autres branches sont indépendantes de votre documentation en ligne, sauf si vous choisissez de les fusionner dans votre branche de déploiement.

Les branches vous permettent de créer des instances distinctes de votre documentation pour apporter des modifications, obtenir des relectures et tester de nouvelles approches avant la publication. Votre équipe peut travailler sur des branches pour mettre à jour différentes parties de la documentation en parallèle, sans modifier ce que les utilisateurs voient sur votre site en ligne.

Le schéma suivant montre un exemple de workflow de branches où une branche de fonctionnalité est créée, des modifications sont apportées, puis la branche de fonctionnalité est fusionnée dans la branche principale.

Nous recommandons de toujours travailler à partir de branches lors de la mise à jour de la documentation afin de garder votre site en ligne stable et de permettre des workflows de relecture.

​

Conventions de nommage des branches

Utilisez des noms explicites et descriptifs qui indiquent clairement l’objectif de la branche.

À utiliser :

• fix-broken-links
• add-webhooks-guide
• reorganize-getting-started
• ticket-123-oauth-guide

À éviter :

• temp
• my-branch
• updates
• branch1

​

Créer une branche

Avec l’éditeur web

1. Cliquez sur le nom de la branche dans la barre d’outils de l’éditeur.
2. Cliquez sur New Branch.
3. Saisissez un nom descriptif.
4. Cliquez sur Create Branch.

Avec un environnement de développement local

1. Créer une branche depuis votre terminal

   git checkout -b branch-name
   

   Cette commande crée la branche et bascule dessus en une seule fois.

2. Pousser la branche sur GitHub

   git push -u origin branch-name
   

   L’option -u configure le suivi pour que les prochaines exécutions se fassent simplement avec git push.

​

Enregistrer les modifications sur une branche

Avec l'éditeur web

Cliquez sur le bouton Save as commit dans le coin supérieur droit de la barre d’outils de l’éditeur. Cela crée un commit et envoie automatiquement votre travail sur votre branche.

Avec un environnement de développement local

Préparez, validez, puis poussez vos modifications.

git add .
git commit -m "Describe your changes"
git push

​

Changer de branche

Utiliser l'éditeur web

1. Sélectionnez le nom de la branche dans la barre d’outils de l’éditeur.
2. Sélectionnez la branche vers laquelle vous voulez passer dans le menu déroulant.

Les modifications non enregistrées seront perdues lors du changement de branche. Enregistrez d’abord votre travail.

Utiliser le développement local

Passez à une branche existante :

git checkout branch-name

Ou créez une nouvelle branche et passez dessus en une seule commande :

git checkout -b new-branch-name

​

Fusionner des branches

Une fois que vos modifications sont prêtes à être publiées, créez une pull request (demande de fusion) pour fusionner votre branche dans la branche de déploiement.