DITA branch and merge:

A dream or a nightmare?

Tristan MitchellDeltaXML

Jean-François AmeyeIXIASOFT

Unrealistic dreams

The Perfect Document

Correct first time and never needs changing

Reality kicks in

Simple updates

v1 v1.1 v1.3v1.2

Change tracking and version diffing suffice

The nightmare begins

v1 v1.1 v1.2

v2 v2.1

v3

Managing multiple branches

The nightmare begins

Original image: http://nvie.com/posts/a-successful-git-branching-model/

Dreaming the dream

Shared nightmares

Banishing the nightmare

Well-formed Valid Fewer conflicts

Cherry pick Auto-resolve GranularityIcons made by Freepik from www.flaticon.com are licensed under CC BY 3.0

The dream becomes reality

Overview of branch merging in IXIASOFT DITACMS

Implementing

DeltaXML Merge

in

IXIASOFT DITA

CMSCMS/DITA North America 2015

Four steps process

1. Find files that have changed between versions

2. Run DeltaXML Merge on changed files

3. Transform resulting merge document to let the

user select the changes to apply

4. Save merged file in the CMS

Run DeltaXML Merge

• The DITA CMS provides three files to DeltaXML:

the common ancestor, the source and the target

• For now, we’ve only implemented the merge feature for two versions only

Run DeltaXML Merge

• DeltaXML returns a “merged file”, which contains

additional XML markup to indicate the changes

The merged file contains non-DITA markup that indicate

the changes as well as their source

DeltaXML merged file

Transform merged file

• The merged file can be transformed back into

standard DITA by using XSLT

Whether to “accept” the changes automatically, or how

to present them to the user, is up to the application

• In the DITA CMS, we decided to transform the

changes into track changes information for the

XML editor, and let the user accept them

In this demo, we have transformed the changes into

oXygen track changes processing-instructions.

Merged file presented to the user

Dreaming new dreams

What other possibilities could merge provide?

Summary

Simple workflowsUse change tracking and diffing to manage change

Complex branchingUse an XML specific merge tool to move changes between branches

Merge tool requirementsWell-formed results

Valid results

Minimize conflicts

Cherry-pick changes

Auto-resolve conflicts

Configurable granularity

Questions?