Design notes, plans and ideas by JulianFoad

Guiding Users into Simple and Safe Merging


Make it much harder to merge the “Wrong Way” by accident.

My goal in one sentence is to stop people accidentally messing up by not understanding what they're doing. I believe one of the main reasons people get their mergeinfo into a mess (from our point of view as developers) is by running Subversion merges without having the correct understanding of what those commands are doing, and by not having a good enough view (reporting) of what they have done. In other words, we make it too easy for users to execute silly merges and not notice until it's too late. We should steer them towards the most common cases and display feedback that indicates whether they're doing something "simple and expected" or something "wierd" that they might not have meant.

Identify the typical merging tasks, which may vary depending on the requirements of the user’s team. Make the typical merging tasks easy to perform; look at TortoiseSVN and other existing GUIs for examples. Clearly distinguish tasks that have different meanings but may currently have similar or identical syntax, to reduce the risk of a user performing a merge that produces the desired output now but will adversely affect future merges. Make it harder to accidentally specify merges that are unusual and not well supported.

Implement these measures by building onto Subversion’s existing library API, command-line UI, client-server interface and/or any other suitable level. If this requires knowledge of the user’s branching model and rules, provide a simple way to configure this and provide one or more typical configurations.

A pre-requisite for designing and implementing such guidance is a clear statement of what merging scenarios Subversion supports. See the document Supported Merge Scenarios.

Pitfalls & Quick Fixes

The aim here is to list things that users might do in Subversion that are not Right — that is, things that will not lead to consistent and useful results in merging later on — that could be avoided by some high-level checks or by better informing the user.

Using branch naming terminology defined in BranchingMergingTerminology.

Common misconceptions

Reporting -- What “svn merge” Should Say

“svn merge” should first of all give a summary of what it is about to do, using words that make sense to the user. Consider stopping to ask for confirmation (unless --no-interactive). Some of the output should be a summary of what is calculated as needing to be merged. That is not only a chance to check the user’s expectation, but in a merge that involves significant calculating of source revisions, it is also a chance for the user to see that Subversion has been doing something useful up to this point and is about to move on to the next stage of actually merging those revisions.

So for example:

$ svn co $URL/branches/dev1 wc1
$ cd wc1
$ svn merge --reintegrate ^/branches/feature2
Reintegrating '/branches/feature2' into working copy of '/branches/dev1'

and then a summary of the current merging status:

Previous merges from ‘/branches/feature2’ into ‘/branches/dev1’
4 source changes (latest: r144) in 2 merges (latest: r145)

and any warnings:

warning: working copy contains modifications (all in ‘docs/’)

warning: working copy is not up to date

warning: ‘/branches/feature2’ is not up to date with ‘/branches/dev1’:
   2 changes (latest: r166) have not yet been merged.
   Run ‘svn mergeinfo’ for details.

Reporting -- What “svn mergeinfo” Should Say

In order for a user to understand what merges they have done and need to do, it would be most helpful if Subversion could tell them the current state of a branch with regard to merges. The 1.7 “svn mergeinfo” command is near useless for such understanding: it just outputs a list of revnums without saying what that means in terms of whether the target is fully caught up or not; it doesn’t report anything meaningful about subtree merges and doesn’t even notice them by default; it doesn’t check that you specified a sensible source branch and simply says nothing if you accidentally specified the target branch.

See MergeinfoCommand.

Diff of Mergeinfo Only (feature)

After doing a merge into my working copy, I wanted to know what changes Subversion thinks it has merged. My current option seems to be "svn diff" and manually try to filter out everything except mergeinfo changes. It would be good to have a dedicated way to show mergeinfo changes.

UI suggestions:

It's probably more useful for plain "svn mergeinfo" (with no source branch specified) to default to this kind of behaviour than to default to displaying info about merges from (only) the default source branch. If that doesn't fit the specification of the "svn mergeinfo" command very well and it continues to be able to display info about merges from a specific source branch, then perhaps "svn mergeinfo" should continue to require a source branch to be specified and not choose a default source branch.

Mergeinfo Diff (bug)

Diff, when displaying an added mergeinfo property on a sub-tree, should diff against the previously inherited mergeinfo, not say that all this new mergeinfo represents merges that have just been done. Similarly for a deleted prop.

Discussed in this email thread.

Mergeinfo command - backward compatibility

If you specify --show-revs={eligible|merged} you'll get the old simple list of revs, and if you don't specify either of those then you'll get the new summary instead. Discussed in this email thread.

SimpleAndSafeMerges (last edited 2012-10-02 21:07:18 by JulianFoad)