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


Regarding this:
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.

My first instinct is to say, just don't.  Ok, that's not an answer.  My second instinct is to slap your wrist for the lack of granular commits and descriptive messages.  I do consider that a viable answer.  Have a meeting and instill good habits!  (if you're worried about merging too many commits into develop at a go, look up squash commit.)

The practice of creating a local feature branch, and then pushing that feature branch out to origin should be your starting point.  Now you have two branches...  One that's local and one that's remote.  As you work on the local, when you reach a milestone you can add/commit the affected files, and then push them out to the remote.  Note that push will only push out committed files.  So you can have a number of files that you have changed on local, plus a number of other files you have changed AND committed on local.  When you push, only the latter set will go out to remote.  At any time, you can merge your remote into develop, because it only has finished files.  So you can use this as a way to stage your work in a way that, WITH PROPER PLANNING AND GOOD HABITS, you can incrementally merge your work into develop.

There is a fly in this ointment.  In all cases, you MUST REGULARLY (at least once a day, plus just before you plan any merge into develop) check out develop, pull, check out your feature branch, then merge develop...  And then push the merged-into feature branch out to remote feature.  Only then will the remote of your feature branch be in sync with ongoing changes in develop.    Here's the problem...  If you have un-committed changes in your local feature branch, git will not allow a merge from develop (for obvious reasons). 

All is not lost...  Git has a workaround.  Before you do the merge, execute git stash. This hides all your un-committed changes.  Then you can merge develop into your feature branch, push, and then execute git stash pop to reveal your hidden files.  This almost covers all your bases.  But still a fly in the ointment...  Stash will not hide a new file.  If you have added a file to your local, and you have not committed that change, stash will not hide it. 

So...  I believe that in nearly all reasonable cases, this can handle your situation.  You need:
  • Reasonable planning. I question the need to merge a subset of a feature branch -- maybe you need more than one feature branch in this case?  Are you dividing feature branches by task, or by so-called feature in the documentation?  I suggest the former.  But if you are legitimately working on unfinished changes, and you need to merge in already-finished changes, then judicious use of commit and push should take care of you.
  • Clear understanding of Git. Somebody has to step up to be the authority.  And that person needs a contact outside of your team who can help you through goofy issues.
  • A local and a remote version of your feature branch.
  • Constant, religious attention to merging develop into your local feature branch, and pushing the merge out to your remote feature branch.
  • A reasonable and clear concept of WHEN to commit/push from local to remote.  Your goal is to make sure the remote feature branch is always ready to merge into develop.
  • Smart management of new files.
  • Occasional use of stash.
Another wrinkle to consider...  One reason to push your feature branch to remote is so that other people can see it and modify it.  If that is your plan, then you muse be even more scrupulous.  And you must not only pull develop and merge it into feature, you must also regularly pull remote feature into local feature. 

I'll say that we work this way all the time.  I was first introduced to Git in this project -- we switched from svn.  We have had people on the project with varying git experience...  Some people with zero experience, and not much command-line confidence either.  Neither fire nor poisonous toads have rained from the sky.  Keep your eyes open, and think ahead.  And yes, you might need to bend some ways of thinking or doing if you want to get the most out of this tool.  That's how technology works...

Join to automatically receive all group messages.