Règles de fusion

Définissez les exigences qui doivent être remplies avant qu’une demande de changement puisse être fusionnée

This feature is available on Pro and Enterprise plans.

Les règles de fusion vous permettent de définir des exigences devant être satisfaites avant que les demandes de modification puissent être fusionnées, par exemple exiger une revue d’un utilisateur spécifique ou demander un sujet ou une description pour la demande de modification.

Ces règles aident à maintenir la qualité du contenu et à garantir des processus de revue appropriés dans votre flux de travail documentaire.

Lorsque vous avez des règles de fusion configurées, elles évalueront automatiquement les demandes de modification avant qu’elles ne puissent être fusionnées. Si une règle n’est pas satisfaite, la fusion sera bloquée jusqu’à ce que les exigences soient remplies.

Cela fournit un moyen automatisé d’appliquer les normes de collaboration et de revue de votre équipe.

Utilisation des règles de fusion

Vous pouvez configurer des règles de fusion à différents niveaux pour correspondre au flux de travail de votre équipe :

Configuration au niveau de l’organisation

Les organisations peuvent définir des règles de fusion par défaut que tous les espaces héritent. Cela apporte de la cohérence entre plusieurs espaces tout en permettant aux espaces individuels de personnaliser leurs règles si nécessaire.

Pour configurer les règles de fusion de votre organisation, ouvrez le menu de l’organisation en haut de la barre latérale et choisissez Paramètres . Sur l’écran Paramètres, sélectionnez Règles de fusion sous la Organisation section de la barre latérale. Ici, vous pouvez spécifier les règles de fusion pour l’ensemble de votre organisation.

Choisissez entre une fusion sans restriction, ou sélectionnez parmi la liste de préréglages à appliquer aux demandes de modification de l’ensemble de votre organisation.

Configuration au niveau de l’espace

Que vous ayez activé ou non des règles de fusion à l’échelle de l’organisation, chaque espace peut avoir ses propres exigences de fusion adaptées à son contenu et à la structure de son équipe.

Cela vous donne la flexibilité d’appliquer des règles plus strictes pour la documentation importante et des règles plus souples pour le contenu en brouillon.

Lors de la configuration des règles de fusion pour un espace, vous pouvez choisir de :

• Hériter des règles de fusion de votre organisation

• Définir des règles personnalisées spécifiques à cet espace

• Désactiver les règles de fusion entièrement

Si vous héritez des règles de l’organisation, toute modification des règles de fusion de l’organisation s’appliquera automatiquement à l’espace.

Pour configurer les règles de fusion pour votre organisation, ouvrez le menu Actions en haut à gauche de l’éditeur, puis sélectionnez Règles de fusion. Ici, vous pouvez spécifier si vous héritez des règles de fusion de votre organisation ou configurer de nouvelles règles spécifiques à cet espace.

Évaluation des règles

Comment fonctionnent les règles

Lorsqu’une personne souhaite fusionner une demande de modification, GitBook évaluera toutes les règles configurées dans l’ordre :

• Toutes les règles d’une configuration doivent être satisfaites pour qu’une fusion soit autorisée

• Les règles sont évaluées dans l’ordre dans lequel elles apparaissent dans votre configuration

• Si une règle échoue, la fusion est bloquée avec un message d’erreur approprié

• Les règles disposant d’une capacité de contournement peuvent annuler des échecs précédents

Règles de contournement

Certaines règles disposent de capacités de contournement (comme Autoriser des acteurs spécifiés à contourner les exigences). Ces règles spéciales peuvent annuler d’autres échecs de règles. Si une règle de contournement évalue à vrai, la fusion sera autorisée même si d’autres règles ont échoué.

Bonnes pratiques

Lors de la configuration des règles de fusion, prenez en compte ces recommandations :

• Commencez simple: Commencez par des règles de base comme exiger au moins une revue.

• Évoluez progressivement: Ajoutez des exigences plus spécifiques à mesure que votre équipe grandit et que les flux de travail mûrissent.

• Utilisez le contournement avec précaution: N’accordez les permissions de contournement qu’à des administrateurs de confiance.

• Revue régulière: Ajustez les règles en fonction des modes réels de travail de votre équipe.

• Testez d’abord: Si possible, testez les modifications de règles dans un espace de test avant de les appliquer aux espaces de production.

Types de règles disponibles

Exigences de revue

Règle	Description
Exiger au moins une revue	Garantit qu’au moins un membre de l’équipe a revu la demande de modification avant qu’elle puisse être fusionnée.
Exiger que toutes les revues soient approuvées	Toutes revues terminées (non demandées) doivent être des approbations. Si un relecteur a demandé des modifications ou a rejeté la demande de modification, la fusion sera bloquée.
Exiger une revue par des acteurs spécifiés	Exige l’approbation de tous les utilisateurs spécifiés. Vous pouvez sélectionner des membres d’équipe spécifiques qui doivent revoir et approuver la demande de modification avant qu’elle puisse être fusionnée.
Exiger une revue par l’un des acteurs spécifiés	Exige l’approbation d’au moins l’un des utilisateurs spécifiés. Ceci est utile lorsque vous avez plusieurs réviseurs qualifiés mais n’avez besoin que d’une seule approbation du groupe.
Exiger une revue par l’agent Docs (bientôt disponible)	Exige une revue de l’agent GitBook IA. Cela garantit que des vérifications automatiques de qualité sont effectuées sur les modifications de contenu avant la fusion.

Exigences pour les demandes de modification

Règle	Description
Exiger que la demande de modification soit à jour	La demande de modification doit être à jour par rapport à la branche principale du contenu. Si le contenu principal a été mis à jour depuis la création de la demande de modification, vous devrez la rebaser ou la mettre à jour avant de fusionner.
Exiger un sujet	La demande de modification doit comporter un sujet/titre descriptif. Les sujets vides bloqueront la fusion.
Exiger une description	La demande de modification doit inclure une description expliquant quelles modifications ont été apportées et pourquoi.

Options avancées

Règle	Description
Autoriser des acteurs spécifiés à contourner les exigences	Vous pouvez désigner des utilisateurs spécifiques autorisés à contourner toutes les autres exigences des règles de fusion. Ceci est utile pour les administrateurs ou les situations d’urgence où les règles doivent être ignorées.
Expression personnalisée	Vous pouvez créer des règles de fusion avancées en utilisant des expressions JavaScript personnalisées. Cela vous permet de définir une logique complexe basée sur le contexte d’évaluation, avec accès aux propriétés de la demande de modification, des revues et de l’utilisateur tentant de fusionner.

Expressions personnalisées

Lorsque vous créez une expression personnalisée, elle sera évaluée chaque fois que quelqu’un tentera de fusionner une demande de modification. Si l’expression renvoie true, la fusion est autorisée. Si elle renvoie false, la fusion est bloquée.

Les expressions personnalisées prennent en charge la syntaxe JavaScript standard (ES2022) et ont une longueur maximale de 1024 caractères.

Variables de contexte disponibles :

• changeRequest.subject - Le sujet/titre de la demande de modification

• changeRequest.description - La description de la demande de modification

• changeRequest.outdated - Si la demande de modification est obsolète (booléen)

• changeRequest.createdBy.id - ID de l’utilisateur qui a créé la demande de modification

• reviews - Tableau d’objets de revue, chacun contenant :

  • reviews[].status - Statut de la revue ("approved" ou "changes_requested")

  • reviews[].reviewer.id - ID du relecteur

• actor.id - ID de l’utilisateur tentant de fusionner

Exemples d’expressions courantes :

Exiger plusieurs revues approuvées

reviews.filter(r => r.status === "approved").length >= 2

Exiger l’approbation d’un utilisateur spécifique

reviews.some(r => r.reviewer.id === "harry" && r.status === "approved")

Exiger une description pour les changements urgents

!changeRequest.subject.includes("[URGENT]") || !!changeRequest.description

Autoriser l’auto-fusion uniquement pour des modifications mineures

changeRequest.createdBy.id === actor.id ? changeRequest.subject.startsWith("[minor]") : true