Demandes de modification

Collaborez sur les modifications de contenu via des demandes de modification

Une demande de modification est une copie de votre contenu principal. Elle provient du concept simple de branchements, et sera familière à toute personne utilisant les pull requests sur GitHub ou les merge requests sur GitLab.

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

Modifiez votre contenu via des demandes de modification.

Créer une demande de modification

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 modification.

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

Une fois satisfait de vos modifications, vous pouvez utiliser le bouton dans la barre d’en-tête pour Demander une relecture de votre demande de modification, ou la Fusionner directement dans la branche principale.

Prévisualiser une demande de modification

Vous pouvez prévisualiser les modifications apportées dans une demande de modification via le bouton de prévisualisation dans l’en-tête de l’espace. Cela vous basculera vers une vue avec vos documents et les modifications proposées dans une fenêtre de prévisualisation, afin que vous puissiez voir vos changements dans le contexte complet de votre documentation publiée.

Vous ne pouvez prévisualiser les demandes de modification que pour les espaces ajoutés à un site de documentation publié.

Si votre contenu est publié via des liens de partage ou un accès authentifié, la fonction de prévisualisation n’apparaîtra pas.

Demander une relecture sur une demande de modification

Demandez une relecture sur votre demande de modification lorsque vous souhaitez demander à des 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 modification 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 modification passera à En relecture, et toute personne taguée dans votre demande recevra une notification.

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

Si vous ne taguez personne dans votre demande de relecture, toute personne ayant des droits de relecteur ou plus recevra une notification concernant votre demande.

Relecture d’une demande de modification

Si vous recevez une demande de relecture d’une demande de modification, vous pourrez modifier le contenu et laisser des commentaires pour vous assurer qu’il est en bon état avant qu’il ne soit fusionné dans la version principale. Vous pouvez soit demander des modifications si vous pensez qu’il reste du travail à faire, soit approuver la demande de modification pour indiquer qu’elle est prête à être fusionnée.

La plupart des relectures auront lieu dans les commentaires de la demande de modification, où les collaborateurs peuvent partager des retours et discuter de blocs de contenu spécifiques, ou de la demande de modification 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 ont été modifiés dans une demande de modification. Elle mettra en surbrillance toutes 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 existe deux options lors de l’utilisation de la vue des différences :

1. Afficher toutes les pages – Il s’agit du mode par défaut de la vue des différences, qui affichera à la fois les pages modifiées et non modifiées dans la table des matières. Cela permet de voir quelles pages ont été modifiées dans le contexte de l’ensemble de l’espace.

2. Afficher uniquement les pages modifiées – Ce mode affichera uniquement 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 passer à l’onglet Modifications pour consulter la vue des différences dans n’importe quelle demande de modification.

Fusionner une demande de modification

Fusionner une demande de modification ajoutera les modifications de la demande à la branche principale du contenu, créant une version mise à jour et une nouvelle entrée dans l’historique des versions de l’espace.

Planifier des fusions

Si vous préférez fusionner les demandes de modification à un moment programmé—par exemple, pour coïncider avec vos cycles de publication produit—vous pouvez utiliser des outils externes comme GitHub Actions ou des plateformes d’automatisation telles que Zapier, connectées via l’API de GitBook.

Par exemple, ajouter ce workflow GitHub fusionnerait une demande de modification une fois par semaine :

.github/workflows/scheduled-gitbook-merge.yml

name: Fusion GitBook planifiée

on:
  schedule:
    - cron: '0 9 * * 3'  # S'exécute chaque mercredi à 09:00 UTC

jobs:
  merge_changes:
    runs-on: ubuntu-latest
    steps:
      - name: Fusionner la demande de modification
        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'

Seuls les administrateurs, créateurs et réviseurs peuvent fusionner les demandes de modification.

Gestion des conflits de fusion

Parfois, lorsque vous souhaitez fusionner une demande de modification, 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 modifier manuellement 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 là auparavant. Cela vous permet de choisir entre une modification et une autre — soit votre travail récent, soit le contenu original.

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 les 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 entièrement. 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 modification

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

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