Overview
Branching in Adobe Experience Manager Guides allows you to create and manage multiple branches out of the main branch for a DITA map to work on different documentation releases in parallel. Each branch allows authors to manage content changes independently, without affecting the corresponding content in other branches.
With branching, multiple teams can work simultaneously on different releases, features, or fixes associated with the same DITA map. You can merge changes from a branch into the default branch (main) when the updates are ready.
How branching works
You can create a branch from the main or any existing branch of a DITA map. After creating a branch, you can switch to it and start editing the map and its content. You can also publish content from the selected branch or merge changes into main when ready.
For example, consider a DITA map named install-the-lift.ditamap that contains installation instructions for a product. Your documentation team can create two branches of this map from main:
- Release 1: Team A maintains existing installation instructions and addresses fixes.
- Release 2: Team B develops installation instructions for new features.
Both teams can work independently on their respective map branches without affecting each other’s changes.
When you create a branch of a DITA map, Experience Manager Guides does not automatically copy the map’s referenced topics into the new branch. Unchanged topics are read from the source branch or the default branch (main). A topic is copied into the new branch only when you edit and save it in that branch.
For example, A DITA map references 100 topics, and the repository contains 50 additional topics that are not referenced by the map. When you create a new branch (release-1.0), all 100 referenced topics automatically become part of release-1.0, even if none of them are edited. The 50 unreferenced topics do not automatically become part of the new branch. If you edit 10 of them, only those 10 become part of release-1.0. The remaining 40 unchanged topics continue to be used from the default branch (main).
Key benefits
Working with a branch in Experience Manager Guides provides the following benefits:
- Isolated editing: Make changes within a selected map branch without affecting the corresponding content in other branches.
- Parallel authoring: Enable multiple teams to work simultaneously on different releases, features, or fixes within their respective map branches.
- Independent publishing: Publish documentation from individual map branches without waiting for changes in other branches to be completed.
- Controlled merging: Merge changes from a map branch into the default branch (
main), with the ability to review and resolve conflicts.
Branching vs. Baselines
A baseline identifies a specific combination of topic versions for a DITA map, allowing you to generate output using those selected versions.
A branch provides a separate editing environment for a DITA map and its content, allowing authors to make changes without affecting other branches of the same map.
Upcoming functionalities
The following functionalities are currently supported only in the default branch (main) and are planned to be supported in other branches of a DITA map in future releases of Experience Manager Guides:
- Search
- Find and replace
- Review workflows