Demandes de modification

Une demande de changement est une copie de votre contenu principal. Elle provient du concept simple de création de branches, et sera familière à toute personne qui utilise les pull requests sur GitHub ou les merge requests sur GitLab.

Dans une demande de changement, vous pouvez modifier, mettre à jour et supprimer des éléments de votre contenu, demander des relectures de vos modifications, puis les fusionner dans votre version principale pour appliquer tous les changements que vous avez effectués.

Créer une demande de changement

Dans un espace où les modifications en direct sont désactivées, cliquez sur le bouton Modifier dans l'en-tête de l'espace pour démarrer une nouvelle demande de changement.

Ceci ouvrira une nouvelle demande de changement, où vous pourrez modifier ou supprimer du contenu selon les besoins. Vos modifications sont enregistrées automatiquement, et d'autres personnes peuvent vous rejoindre dans une demande de changement pour collaborer en temps réel.

Une fois que vous êtes satisfait de vos modifications, vous pouvez utiliser le bouton dans la barre d'en-tête pour Demander une relecture de votre demande de changement, ou La fusionner directement dans la branche principale.

Aperçu d'une demande de changement

Vous pouvez prévisualiser les modifications que vous avez apportées dans une demande de changement en cliquant sur l' option Aperçu dans le l'en-tête de l'espace. Cela basculera vers un aperçu de vos docs publiés avec les modifications proposées incluses, afin que vous puissiez voir vos changements dans le contexte complet de votre documentation publiée.

Sous le option Aperçu bouton se trouve une URL pour l'aperçu de votre site. Cliquez dessus et l'aperçu de votre site s'ouvrira en plein écran dans un nouvel onglet.

Lorsque vous ouvrez une URL d'aperçu dans un nouvel onglet, vous verrez également la barre d'outils Aperçu en bas de la fenêtre du navigateur. Cette barre d'outils vous permet de revenir rapidement dans GitBook pour afficher, modifier ou commenter la demande de changement, ou d'ouvrir la version en ligne de votre site.

Demander une relecture d'une demande de changement

Demandez une relecture de votre demande de changement lorsque vous souhaitez demander aux membres de votre équipe de vérifier votre contenu avant de fusionner les modifications dans la branche principale.

Vous pouvez ajouter une description à votre demande de changement pour donner du contexte à vos relecteurs, et taguer des personnes spécifiques que vous souhaitez voir vérifier votre travail.

Lorsque vous cliquez sur Demander une relecture, le statut de la demande de changement passera à En cours de relecture, et toute personne que vous aurez taguée dans votre demande de relecture recevra une notification.

Si vos modifications ne nécessitent pas de relecture, vous pouvez fusionner directement vos modifications dans la version principale à la place.

Relecture d'une demande de changement

Si vous recevez une demande de relecture d'une demande de changement, vous pourrez modifier le contenu et laisser des retours pour vous assurer qu'il soit en bon état avant sa fusion dans la version principale. Vous pouvez soit demander des modifications si vous pensez qu'il nécessite encore du travail, soit approuver la demande de changement pour signaler qu'elle est prête à être fusionnée.

La plupart des relectures auront lieu dans les commentairesde la demande de changement, où les collaborateurs peuvent partager des retours et engager des discussions sur des blocs de contenu spécifiques, ou sur la demande de changement dans son ensemble.

Vue des différences

Lorsque vous ouvrez l'onglet Modifications dans l'en-tête de l'espace, la vue des différences apparaîtra. La vue des différences met en évidence chaque page et bloc qui a été modifié dans une demande de changement. Elle mettra en évidence les pages modifiées dans la table des matières, et sur les pages elle montrera les blocs spécifiques qui ont été ajoutés, modifiés ou supprimés.

Il y a deux options lors de l'utilisation de la vue des différences :

1. Afficher toutes les pages – C'est le mode par défaut pour la vue des différences, qui affichera à la fois les pages modifiées et non modifiées dans la table des matières. C'est utile pour voir quelles pages ont été éditées dans le contexte de l'ensemble de l'espace.

2. Afficher uniquement les pages modifiées – Ce mode n'affichera que les pages modifiées dans la table des matières, ce qui vous aide à vous concentrer sur le contenu modifié. Cela est particulièrement utile dans les grands espaces avec de nombreuses pages et sous-pages.

Vous pouvez basculer vers l'onglet Modifications pour vérifier la vue des différences dans n'importe quelle demande de changement.

Fusion d'une demande de changement

La fusion d'une demande de changement ajoutera les modifications de la demande de changement dans la branche principale du contenu, créant une version mise à jour et une nouvelle entrée dans l'historique des versions.

Planification des fusions

Si vous préférez fusionner les demandes de changement à un moment planifié — par exemple, pour les aligner sur vos cycles de sortie produit — vous pouvez utiliser des outils externes comme GitHub Actions ou des plateformes d'automatisation telles que Zapier, connectés via l'API de GitBook.

À titre d'exemple, ajouter ce workflow GitHub fusionnerait une demande de changement une fois par semaine :

name: Fusion GitBook planifiée

on:
  schedule:
    - cron: '0 9 * * 3'  # S'exécute tous les mercredis à 09:00 UTC

jobs:
  merge_changes:
    runs-on: ubuntu-latest
    steps:
      - name: Merge Change Request
        run: |
          curl -X POST https://api.gitbook.com/v1/spaces/{space-id}/change-requests/{change-request-id}/merge \
          -H 'Authorization: Bearer YOUR_API_KEY' \
          -H 'Content-Type: application/json'

Gestion des conflits de fusion

Parfois, lorsque vous souhaitez fusionner une demande de changement, vous pouvez découvrir des conflits entre le contenu principal et le contenu que vous essayez de fusionner. Dans sa forme la plus simple, un conflit est un élément de contenu qui n'a pas pu être fusionné automatiquement.

Si cela se produit, une alerte de conflit vous sera présentée, ainsi qu'une liste des conflits que vous devrez résoudre avant de poursuivre la fusion.

Résolution des conflits de fusion

Vous avez deux options pour résoudre un conflit de fusion — sélectionner une version à fusionner ou manuellement modifier le contenu.

Sélectionner une version à fusionner

Vous pouvez résoudre un conflit de fusion en sélectionnant la version que vous souhaitez fusionner — soit votre contenu entrant, soit le contenu qui était précédemment en place. Cela vous permet de choisir entre une modification et une autre — soit votre travail récent, soit le contenu d'origine.

Si vous êtes confronté à un conflit de fusion qui peut être résolu de cette manière, vous pouvez sélectionner la version que vous souhaitez conserver, et l'autre version sera supprimée.

Modification manuelle

Si vous ne souhaitez pas choisir entre des versions, vous pouvez résoudre un conflit de fusion en modifiant manuellement le conflit. Vous pourrez supprimer les blocs dont vous n'avez pas besoin, ou même les réécrire complètement. Une fois que vous êtes satisfait des modifications, vous pouvez passer au conflit suivant jusqu'à ce qu'ils soient tous résolus.

Archivage d'une demande de changement

Si vous décidez de ne pas fusionner une demande de changement et que vous souhaitez la retirer de la file d'attente, vous pouvez l'archiver.

Pour archiver une demande de changement, ouvrez-la d'abord. Ensuite, cliquez sur le menu Actions à côté du titre de la demande de changement et choisissez Archiver. Vous pouvez retrouver et rouvrir les demandes de changement archivées plus tard en ouvrant le menu Demandes de changement et en sélectionnant l'onglet Archivées .