Travailler avec des branches

Créez et gérez des branches de documentation pour prévisualiser les modifications, collaborer avec vos coéquipiers et fusionner les mises à jour avant publication en production.

Les branches sont une fonctionnalité de gestion de versions qui pointent vers des commits spécifiques dans votre dépôt. Votre deployment branch, généralement appelée main, représente le contenu utilisé pour compiler votre site de documentation publié. Toutes les autres branches sont indépendantes de votre site publié, sauf si vous choisissez de les fusionner dans votre deployment branch.

Les branches vous permettent de créer des instances distinctes de votre documentation pour apporter des modifications, obtenir des révisions 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 publié.

Le schéma suivant montre un exemple de workflow de branches où vous créez une feature branch, apportez des modifications, puis fusionnez la feature branch dans la main branch.

Travaillez toujours à partir de branches lors de la mise à jour de la documentation afin de garder votre site publié stable et de permettre les workflows de révision.

Conventions de nommage des branches

Utilisez des noms explicites et descriptifs qui indiquent clairement l’objectif d’une branch.

À utiliser :

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

À éviter :

temp
my-branch
updates
branch1

Créer une branch

Cliquez sur le nom de la branch dans la barre d’outils de l’éditeur. Si vous ne le voyez pas, affichez le sélecteur de branch.
Dans Find a branch, saisissez un titre descriptif. Si vous le laissez vide, l’éditeur nomme la branch d’après la date actuelle.
Cliquez sur New branch.
Si vous avez des modifications en attente, choisissez Bring them to this branch ou Leave them behind. Votre branch d’origine conserve ses modifications en attente dans les deux cas.

Créer une branch depuis votre terminal

git checkout -b branch-name

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

Pousser la branch sur GitHub

git push -u origin branch-name

L’option -u configure le suivi pour que les prochains push se fassent simplement avec git push.

Enregistrer les modifications sur une branch

Vous n’avez pas besoin d’enregistrer manuellement. L’éditeur commit vos modifications sur la branch environ 15 secondes après que vous arrêtez d’écrire. Le premier commit ouvre une pull request vers votre deployment branch.

Préparez, commitez, puis poussez vos modifications.

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

Changer de branch

Cliquez sur le nom de la branch dans la barre d’outils de l’éditeur pour ouvrir la liste déroulante des branches.
Recherchez une branch par nom ou parcourez la liste.
Cliquez sur la branch vers laquelle vous souhaitez basculer.

Chaque branch dans la liste déroulante affiche un indicateur de pull request, ce qui vous permet de voir si la branch a une pull request ouverte, en brouillon, fusionnée ou fermée, ou aucune pull request pour le moment.

Avant toute recherche, la liste déroulante répertorie les branches créées dans l’éditeur et les branches ayant une pull request ouverte ciblant votre deployment branch. La recherche par nom fait aussi remonter d’autres branches de votre dépôt, y compris les branches poussées directement via Git et les branches dont la pull request est fusionnée ou fermée. Consultez Branch absente de la liste des branches de l’éditeur web.

Vos modifications en attente restent sur la branch que vous quittez.

Passez à une branch existante :

git checkout branch-name

Ou créez une nouvelle branch 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, fusionnez votre branch dans la deployment branch.

Si Mintlify héberge votre dépôt et que votre branch ne requiert pas d’approbations, cliquez sur Publish dans la barre d’outils de l’éditeur, puis sur Publish pour fusionner votre branch et publier vos modifications.

Sinon :

Cliquez sur Publish dans la barre d’outils de l’éditeur, puis sur Request review. Cela marque la pull request de votre branch comme prête à être relue.
Effectuez les révisions et vérifications requises.
Cliquez sur Publish, puis sur Merge and publish.

Consultez Publier vos modifications pour savoir comment les actions de publication disponibles changent en fonction de votre branch et des protections de branch.

Poussez votre branch, puis ouvrez une pull request dans votre fournisseur Git qui cible votre deployment branch. Une fois la pull request fusionnée, Mintlify compile et déploie vos modifications sur votre site publié.

Supprimer une branch

Supprimez les branches dont vous n’avez plus besoin afin de garder la liste déroulante des branches facile à gérer.

Cliquez sur le nom de la branch dans la barre d’outils de l’éditeur pour ouvrir la liste déroulante des branches.
Survolez la branch que vous souhaitez supprimer.
Cliquez sur l’icône de corbeille Delete branch.
Cliquez sur Delete branch pour confirmer.

La suppression d’une branch ferme toute pull request ouverte pour cette branch et supprime la branch de votre dépôt. Vous ne pouvez pas supprimer votre deployment branch.

Supprimez la branch localement :

git branch -d branch-name

Puis supprimez-la de votre dépôt distant :

git push origin --delete branch-name