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

Kristen James Eberlein

Thank you, Chris, Alastair, and Jean-Noël for your feedback.

I do want to set some additional context here:

  • I am familiar with and comfortable with Git, although it is new to the technical writers on this project. (And perhaps frightening to the manager.) I started using Git when the DITA-OT project moved to it from SVN, and I'm still grateful for all the help that Jarno Elovirta, Robert Anderson, and Roger Sheen gave me as I learned Git.
  • Yes, good practices for Git are just standard, good software development practices: Keep feature branches discrete; update feature branches by pulling from the current development repository frequently; commit thoughtfully and frequently with good commit messages, so that cherry picking is a possibility.
  • For this project, the technical writers are using oXygen, and we can control formatting through common project files to reduce conflicts.

That said, version control with Git can have a steep ramp-up for technical writers. Any thoughts about how to best minimize that? Useful resources?

And how to best plan a process for the scenario in which a writer wants to merge some (but not all content) from a feature branch into the development branch? In the absence of granular commits with descriptive commit messages, cherry picking is a not a realistic option.

So far I've handled this manually, by asking the writer for names of the files that she wanted merged; merging them into a local copy of the development branch; resolving merge conflicts and QA errors (errors in DITA source, spelling); and eventually merging into the development branch.


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

On 12/18/2019 6:13 AM, Alastair Dent wrote:
Using Git requires a change in thinking.

All authors need to abandon the thoughts of 'check out', 'check in', 'lock'. Those don't really apply to git.
New concepts that are absolutely essential to learn are 'remote', 'origin', 'branch'.

When an author pulls a repository ( pulling a copy of the main repository), they are creating a local repository. Their work will take place in this repository. Usually, good practice is to create a local branch for new work. *Always* update your local repository before starting a new piece of work (fetch and pull the latest updates from the origin).

When working on DITA files, the files are numerous and small. It is unusual for two authors to both edit the same file at the same time. Frequent updates and pushes are the way to work. 

This is no different to programmers working on code. 

Join to automatically receive all group messages.