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

Jean-Noël AVILA

What you are pointing out is basically rewriting the history of feature
branches, which is totally against Git's way of doing in its standard
usage. In this case, there's need for more advanced git management, with
all the required caveats.

So first of all, if we are to rewrite history, it's mandatory to not
introduce merge commits. Basically that means rebasing feature branches.
Be careful to make people understand that these rebased feature branches
can not be modified by more than one writer.

Then, when it's time to cherry pick the changes, I would put on the
"expert mode":

* Checkout the branch and rebase it on top of develop
* Reset the working copy to develop. The history seems to be at
develop, but the working copy holds all the changes of the branch.
As a result, all the changes of the branch are available in the
working copy for selection of hunks to add to the next and unique
* Stage changes that go in the commit (for later merge into develop)
hunk by hunk,effectively leaving in the working copy changes that
won't make it into develop.
* Commit the changes to be merged, stash the rest
* Check out develop, spawn a new branch, unstash and commit as the
branch "not merged".
* Merge the first branch into develop.

This is quite involved, but that's a minimum to rewrite history.


Le 19/12/2019 à 14:03, Kristen James Eberlein a écrit :

I really appreciate everyone's feedback and advice; it reminds me what
a wonderful community we have here! Chris, thanks especially for your
most recent e-mail.

Yes, education about Git and Git best practices is critical. It's my
current priority to help the team with that.

And to those who are saying "Why hasn't Kris helped them with that
already?," I need to say that getting people from 0 to 60 miles/ 100
km a hour is impossible to do overnight. My initial focus was 1) build
automation, and 2) ensuring that the DITA source was free of errors.
While this is a small help system (1,725 topics), it is loaded with
cross references (4,312) and images (1,408). The technical writers
badly needed to understand the concept of dependencies, and the
cascading effects of deleting or refactoring a topic.

So back to Git and the key issue of technical writers needing to
*merge some (but not all) of a feature branch into the development
branch* ... This is a result of how product management operates.

*Here is the typical scenario.* Product management opens a Jira ticket
that focuses on needing to document a new product feature (or change
in product architecture) into the documentation. The manager does her
best to qualify and negotiate scope, and then assigns the ticket to a
technical writer. The technical writer assesses the impact to the
existing documentation (and its spaghetti structure); she tries to
understand and stage the work as best as possible. The technical
writer works hard on improving the content. But approval for deploying
the content falls to product management. When they do review the
content, they want to tweak words, and so postpone deploying the
content for a cycle. Next cycle, they want to cherry pick what is
deployed: "I'm good with this; it can go. No, this needs more work; it
should wait for another release."

Obviously, this is not a good or sustainable workflow, and changing it
is a big priority for the manager. But it's not going to change
overnight. Remember that the manager and the technical writers are new
to the company and the product. Luckily they are smart and determined.

So I'm still left trying to determine what are the best processes that
I can immediately put in place to mitigate pain and churn. I'm leaning

* Better planning for documentation changes that require feature
branches. Can the feature branches be more modular? Better planned
and scoped?
* Increased education about Git best practices, especially around
working with feature branches 
* Team guidelines for guidelines for 1) what go should go into a
commit, and 2) commit messages
* Mentoring one of the technical writers as he ramps up to become
the team Git expert (already underway)

I'll have to think about whether commiting but not pushing some files
and then stashing them is an option. I suspect not, since content in
the feature branch needs to pushed in order to generate build
artifacts that the stakeholders can download and review.


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

Join to automatically receive all group messages.