DITA and Git: Minimizing merge conflicts #version-control #change-management

Kristen James Eberlein

This might be slightly off-topic, but certainly Git is version control for many companies' DITA implementations.

Short version: What tactic have you found best to minimize merge conflicts for new technical writers working in Git?

Gruesome detail: I am working with a client who stores their DITA content in GitLab. They are using SourceTree as a client. Before I was brought on-board, there was turnover and the team reduced to a manager and two technical writers, all brand-new to DITA, Git, and version control. Infrastructure engineers set up an automated build for them and recommended that they use the following practices:

  • A development branch that is merged into master every two weeks when new content is delivered to the public-facing Web site.
  • "Feature" branches for technical writers to use to work on new content that might span several development cycles. These branches are created from the most recent development branch.

These feature branches are problematic. Often by the time that the technical writer wants to merge them into the current development branch, there are many merge conflicts. Or the technical writer wants to selectively add in some (but not all) changes that have been made in the feature branch.

I'm trying to think of processes this team can use that will minimize merge conflicts. Here are some of the approaches I've considered:

  1. Update the feature branch frequently by pulling the current development branch into the feature branch.
  2. Leave the feature branch alone. Do not update it by pulling the content from the the current development branch into the feature branch. When it comes time to merge the feature branch into the development branch:
    1. Try to do it automatically.
    2. If there are significant merge conflicts, build a "patch of modified files" by diffing 1) the feature branch as it was first created, and 2) the feature branch at its current point in time. Apply the patch to the current development branch.
Have I missed something? Any advice? I have not been able to think of any non-manual solutions to the "I want to merge some but not all work from my feature branch in the development branch. And a CCMS is not an option.


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 622-1501; kriseberlein (skype)

Join main@dita-users.groups.io to automatically receive all group messages.