Règles de fusion

Définissez les exigences qui doivent être remplies avant que les demandes de modification puissent être fusionnées

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

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 configuré des règles de fusion, elles évalueront automatiquement les demandes de changement avant qu’elles 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 standards 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 toutes les sections héritent. Cela garantit une cohérence entre plusieurs sections tout en permettant à chaque section de personnaliser ses règles selon ses besoins.

Pour configurer les règles de fusion pour votre organisation, retournez à votre organisation Accueil et cliquez sur Paramètres , sous Admin dans la barre latérale. Dans l’écran des paramètres, cliquez sur Règles de fusion dans le groupe Organisation . Ici, vous pouvez spécifier des règles de fusion pour l’ensemble de votre organisation.

Choisissez entre une fusion sans restriction, ou sélectionnez l’un des préréglages pour les appliquer aux demandes de changement dans toute votre organisation.

Configuration au niveau de la section

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

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

Lors de la configuration des règles de fusion pour une section, vous pouvez choisir de :

• Hériter des règles de fusion de votre organisation
• Définir des règles personnalisées spécifiques à cette section
• 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 à la section.

Pour configurer les règles de fusion d’une section, ouvrez Menu d’actions dans la partie supérieure gauche de l’éditeur, puis cliquez sur Règles de fusion. Ici, vous pouvez spécifier s’il faut hériter des règles de fusion de votre organisation ou en configurer de nouvelles spécifiques à cette section.

Évaluation des règles

Comment fonctionnent les règles

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

• Toutes les règles d’une configuration doivent être validées pour qu’une fusion soit autorisée
• Les règles sont évaluées dans l’ordre où elles apparaissent dans votre configuration
• Si une règle échoue, la fusion est bloquée avec un message d’erreur approprié
• Les règles avec capacité de contournement peuvent annuler les échecs précédents

Règles de contournement

Certaines règles disposent d’une capacité 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 est évaluée à 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, tenez compte de ces recommandations :

• Commencer simplement: Commencez par des règles de base, comme exiger au moins une revue.
• Évoluer progressivement: Ajoutez des exigences plus spécifiques à mesure que votre équipe grandit et que les flux de travail mûrissent.
• Utiliser le contournement avec prudence: N’accordez les autorisations de contournement qu’aux administrateurs de confiance.
• Réviser régulièrement: Ajustez les règles en fonction des schémas réels de travail de votre équipe.
• Tester d’abord: Lorsque c’est possible, testez les modifications de règles dans une section de test avant de les appliquer aux sections 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 changement avant qu’elle puisse être fusionnée.
Exiger que toutes les revues soient approuvées	Toutes terminées les revues (non demandées) doivent être des approbations. Si un relecteur a demandé des modifications ou a rejeté la demande de changement, la fusion sera bloquée.
Exiger une revue par des acteurs spécifiés	Nécessite l’approbation de tous les utilisateurs spécifiés. Vous pouvez sélectionner des membres précis de l’équipe qui doivent examiner et approuver la demande de changement avant qu’elle puisse être fusionnée.
Exiger une revue par l’un des acteurs spécifiés	Nécessite l’approbation d’au moins un des utilisateurs spécifiés. C’est utile lorsque vous avez plusieurs relecteurs qualifiés, mais qu’une seule approbation du groupe est nécessaire.
Exiger une revue de Docs Agent (bientôt disponible)	Nécessite une revue de l’agent IA de GitBook. Cela garantit que des vérifications automatiques de qualité sont effectuées sur les modifications de contenu avant la fusion.

Exigences relatives à la demande de changement

Règle	Description
Exiger une demande de changement à jour	La demande de changement doit être à jour avec la branche de contenu principale. Si le contenu principal a été modifié depuis la création de la demande de changement, vous devrez la rebaser ou la mettre à jour avant la fusion.
Exiger un sujet	La demande de changement doit avoir un sujet/titre descriptif. Les sujets vides bloqueront la fusion.
Exiger une description	La demande de changement 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. C’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 à l’aide d’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 changement, des revues et de l’utilisateur qui tente de fusionner.

Expressions personnalisées

Lorsque vous créez une expression personnalisée, elle sera évaluée chaque fois que quelqu’un essaie de fusionner une demande de changement. Si l’expression renvoie vrai, 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 changement
• changeRequest.description - La description de la demande de changement
• changeRequest.outdated - Indique si la demande de changement est obsolète (booléen)
• changeRequest.createdBy.id - ID de l’utilisateur qui a créé la demande de changement
• relectures - 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 courants d’expressions :

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 la fusion par soi-même uniquement pour les changements mineurs

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