Introduction
Branch and merge is a key feature of DITA XML. It’s widely used across the different types of technical writing projects, but it can be challenging to get right. This article reviews some best practices for making sure your branch and merge strategy works well and gives you ideas on what to avoid so that you don’t get into trouble later on.
One of the best features of DITA XML is the ability to share content across various documents, even across various working groups. Branch and merge can really help to provide a solution to sharing content across various products and variants, especially when the technical writing teams are dispersed.
How do we handle content when writers are making changes for a release creates a conflict with the current product documentation that still needs to be updated for example for a hotfix?
When you’re working on a new release, there can be many distinct phases.
A first is when writers are making changes to the content in order to prepare it for the next release. In this phase, there will be conflicts between the “current” product documentation (the material that is currently available) and the updated product documentation (the updated version of your content).
A second phase is when other reviewers are reviewing and approving changes made by writers during the first phase. This can result in additional conflicts between versions of documents if there are problems with any of those approved edits or updates.
Recommendations
Here are eight recommendations to help you avoid some common mistakes while merging and branching in your CMS.
Define the Branch and merge Strategy First
You should define the branch and merge strategy first, before you start working on your documentation. It’s not just a matter of convenience but also to be able to convince the team that this is the best way to go forward, and that the strategy is adaptable enough to take into account hotfixes, last minute feature additions or removals, or selective publication dependent on feature readiness, approval status or any other reason.
As a technical writer, when you work on a feature you might think about how it could affect other parts of the system and how they might need changes as well. The moment you start working on those changes it can become quite difficult to change paths if things don’t go according to plan or if there are any complications along the way.
By defining this strategy early on, it will help everyone understand why they should do things in a particular way so they will have no hesitation when implementing tasks related to branching or merging during development activities such as fixing bugs or adding new features using different branches (for example).
Have different branches for development, features, hotfixes, etc.
Have different branches for development, features, hotfixes, etc.
It’s often tempting to have just one branch and push everything into that single repository. This isn’t a good idea because product managers want to be able to see what’s happening with each release.
When you have multiple branches (for example, Feature, Hotfix, Production), there is an overhead involved in merging them together at various points in time. But this overhead will pay off when you only need to merge two of your branches together and not all of them at once!
Merge as required, when required and as quickly as possible
Merge as required, when required and as quickly as possible.
Develop a streamlined process for merging branches into the main trunk. Merge your feature once it has been reviewed. It is common for features to sit in limbo for weeks or months before being merged into master, avoid this if possible. Keeping track of who needs what from whom (and communicating with those people) will allow you to make a decision to finalize the content and then merge it back into the trunk.
Use permissions to limit who can change what
You should use permissions to limit who can change what.
Permissions are the most powerful and flexible security feature of CCMS. They allow you to define exactly which users have access to do what, and when they can do it. This means that if you’ve set up your permissions correctly, only those people assigned a particular permission level will be able to perform actions like creating a branch, deleting it or performing a merge. If someone unauthorized tries to perform one of these tasks, their attempt will be rejected by the system automatically. It also allows the overall content strategy manager to have a say and maybe provide advice as to how best to introduce new content that is in line with the organization’s content strategy.
Create a “tag” or snapshot each time you branch and merge.
Create a tag or snapshot before and after you need to create a branch or merge branches. This is useful if you need to rollback in case of an audit or simply want to go back to a previous version.
Cleanup unused branches, as soon as they are no longer required.
Remember to tag them first!
If you have branches that are no longer required, clean them up. This will allow you to keep your repository neat and tidy, which makes it easier for everyone else to find what they need. Maintain a clean working directory and commit history on a daily basis.
Use a consistent naming convention for branches. This helps you avoid getting confused later on when looking at your repository’s history.
Use Advanced or Selective Branch and Merge
You can branch a ditamap and pull in only the dependencies (files and folders used by that ditamap). You can always add folders/files to that branch individually if required.
The advantages of this approach are:
- You can develop multiple features in parallel without cluttering up your repository with unnecessary files and folders.
- It makes it easier to track changes when multiple people are working on different ditamaps.
- With fewer files and folders to keep track of, it makes your repository more manageable in general.
- You reduce the amount of data in your CCMS, keeping it fast and fluid, and you end up paying less for storage monetarily and environmentally!
Designate a Branch and Merge Manager
Or someone in the team with a full picture view of the content strategy.
It may be tempting to designate one person as the “branch manager,” but it’s better to give this responsibility to someone in your team with a full picture view of the content strategy. The Branch and Merge Manager will need to know who is working on what, and how that fits into the overall strategy, so they can help you avoid mistakes like duplicating efforts or creating conflicting branches or reuse mechanisms. If they have this information, they can give you guidance as needed and help make sure you’re not wasting time on something that doesn’t fit into the overall plan.
Implement permissions control on branch and merge operations
It’s important to implement some sort of permissions control on branch and merge content changes. This way you can prevent unwanted changes from being introduced into your production environment.
It’s often a good idea to create separate branches for each feature or user story, and then merge them back together after they’ve been completed. This helps keep things organized and makes it easier to track which features are currently deployed in production. This will ensure that you don’t have any accidental changes made to your production environment by mistake.
It could be something as simple as requiring all branch and merge operations be performed by one or two specific people, who then notify the rest of the team when it’s safe to begin using the new content in production.
Implement change review protocols
If you’re implementing your CCMS content strategy so that the root user can make all changes without requiring any permissions checks, then it’s essential that you also implement some sort of change review process in order to ensure quality control. This is especially important if there are multiple branches, as it allows users on each branch to check for errors or undesirable side effects before merging into the trunk or production.
Mistakes to avoid
The biggest mistake is not knowing what’s going on in your content strategy. If you don’t know who is doing what and how it fits into the overall plan, it will be hard to avoid mistakes like duplicating efforts or creating conflicting goals.
- Mistake #1: You do not have a clear understanding of what you want.
- Mistake #2: You do not plan out your actions and steps to get there.
- Mistake #3: You do not ask for help from someone who’s done something similar before.
- Mistake #4: You do not share your conclusions on the strategy you have drafted.
Here are some other mistakes to avoid.
Avoid Not visualizing your branch and merge scenarios
Branch and merge is one of the most powerful new features in a CCMS, but it can feel like a black box for many teams. The best way to get comfortable with the merge tool is to practice with it in a safe environment. The easiest way to do this is by creating some branches, merging them together, and then visualizing what happened when you did so.
There are multiple ways that teams can visualize their branch and merge strategy:
- Draw it out on paper
- Use a whiteboard and sticky notes so you can move the pieces of the puzzle until they fit your strategy
- Use a visualization tool like Miro
Above all, brainstorm and/or share your conclusions with members of your team, and any other actors that may have an impact on your strategy. There is no point having a branch and merge strategy that does not fit with the software department’s release schedule for example.
Avoid Branching unnecessary content like entire repositories or folders
Branching unnecessary content, entire repositories and folders, is a waste of time and resources. Branches are not free, they come with a cost, so you should avoid creating them unless it is absolutely necessary.
This is something you should avoid at all costs. Here’s why:
- Branches are expensive to maintain and can result in a huge increase of repository size (especially if you’re branching large files). This can have a negative impact on your repository performance, particularly if it’s on a slow network or old hardware.
- Branching is slow because it requires changes to be pushed first before pulling them down into the branch — which means that your team will be waiting longer than expected for their work to be available in production.
- Branches need to be merged back together eventually so there’s always going to be some manual intervention required during the merge process.
Avoid merging before comparing content
The entire purpose of branching is to create a safe place to create content for new features, hotfixes or otherwise non-production ready content. But if you’re not careful, it can become a dumping ground for content variants. That’s why it’s important to do some pre-merge checks before merging branches into your main branch. This will help ensure that the changes in your feature branch are ready to be merged into the trunk.
When you do a pre-merge check, you can find out if the content in the feature branch are ready for merge. This will help reduce errors and ensure that your changes are complete before merging into the main branch. In this scenario, you’ll want to compare files between branches to ensure they’re compatible with each other. If they aren’t, then it’s time to figure out what needs to be done before proceeding with the merge.
Avoid Using branch and merge where simple profiling would have sufficed
In the beginning, you probably wanted to profile everything. And then later, you may have figured out that some of the data in your source tables didn’t really need to be part of the profile. So what do you do? You can remove those columns from your source table and create a separate branch for them. However, this means that each time any changes are made to these data sets in the future, you will need to make the changes in each of the branches. Branch and merge should be used for entire data sets that can live independently of each other for longish periods of time, before they then get merged back into the main branch or trunk. Profiling generally should be used to differentiate two or more variations in content that tend to remain so for the entire lifecycle of the content.
Avoid Merging without using Change Controls
Merging without an Extra Step of having to make a Request for Change.
But wait, you say, we can just merge the hotfix branch into master and the new version branch into master. We’ll be fine!
Well, not so fast there. This is a bad idea because merging directly from a hotfix or new version branch to master will often result in merge conflicts—conflicts that have to be resolved manually before you can proceed with your build definition. And that takes time!
Avoid Merging without Checking for and Resolving Merge Conflicts First.
There are two types of merge conflicts: 1-way and 2-way.
When you perform an operation that causes a file to be changed by two or more users at the same time, a 2-way conflict is created in the file: one user made changes in his/her version of the file while another user made corresponding changes in his/her version of the same file at approximately the same time (e.g., both users were working on different parts of the same document). To avoid losing data when resolving these conflicts manually there is always one winner and one loser – meaning some changes will need to be discarded as part of resolving this type of merge issue.
Avoid 2-Way Merge Conflicts
Avoid 2-Way Merge Conflicts by Resolving 1-way conflict issues first.
The goal of this recommendation is to make the resolution of a 2-way merge conflict. This is achieved by resolving 1-way conflict issues first, before resolving 2-way conflict issues. Because 1-way conflict issues are easy to resolve, you should resolve them first so that you can avoid creating a difficult merge conflict later on in your process flow.
Conclusion
Branch and merge can be a powerful tool for managing content in your DITA XML documents, especially when it comes to sharing content across various working groups. It is important that you understand how it works before implementing it into your workflow. For example, make sure you define a strategy first before branching or merging any content into your version controlled environment.
Also consider using 3-way merges instead of 2-way merges if possible so that they don’t get stuck in an unresolved state where nothing gets saved! With a 3-way merge, the CCMS can compare the conflicting files, but it can also compare each of them against the original copy (before either was changed). So it can see the changes in the first files, the changes in the second when compared to the original file. The CCMS can then use that information to produce a merged version.
