Travailler avec des branches
Créez et gérez des branches de documentation pour prévisualiser les modifications, collaborer en équipe et fusionner avant publication en prod.
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ù vous créez une branche de fonctionnalité, apportez des modifications, puis fusionnez la branche de fonctionnalité 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.
Utilisez des noms explicites et descriptifs qui indiquent clairement l’objectif de la branche.
À utiliser :
fix-broken-linksadd-webhooks-guidereorganize-getting-startedticket-123-oauth-guide
À éviter :
tempmy-branchupdatesbranch1
- Cliquez sur le nom de la branche dans la barre d’outils de l’éditeur.
- Cliquez sur Create new branch.
- Saisissez un nom descriptif.
- Si vous avez des modifications non enregistrées, choisissez de les transférer vers la nouvelle branche ou de les laisser sur votre branche actuelle.
- Cliquez sur Create branch.
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.
- Cliquez sur le nom de la branche dans la barre d’outils de l’éditeur pour ouvrir la liste déroulante des branches.
- Recherchez une branche par nom ou parcourez la liste.
- Cliquez sur la branche vers laquelle vous souhaitez basculer.
Chaque branche dans la liste déroulante affiche un indicateur d’état pour que vous puissiez voir si elle est prête, en cours de synchronisation ou en échec.
Les modifications non enregistrées seront perdues lors du changement de branche. Enregistrez d’abord votre travail.
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.