[RFC] A better way to help users understand and resolve confclits

[Vincent Ladeuil]

>>>>> "martin" == Martin Pool <mbp at canonical.com> writes:

<snip/>

    martin> # Begin patch
    martin> === added file 'Outline.txt'
    martin> --- Outline.txt	1970-01-01 00:00:00 +0000
    martin> +++ Outline.txt	2009-08-13 06:21:35 +0000


    martin> I guess you atually want to put this into
    martin> doc/developers/conflict-handling or something?

Yes, I wanted to present the ideas before going too far in test
writing (which still sounds like the best way to find the best
design here regarding user interactions).


<snip/>

    martin> +Whatever the conflict is, resolving it is roughly done in two steps:
    martin> +
    martin> +- modify the working tree content so that the conflicted item is
    martin> +  now in the desired state, there are,
    martin> +
    martin> +- inform bzr that the conflict is now solved and ask to cleanup
    martin> +  any remaining generated information (``bzr resolve <item>``).

    martin> That's true at the moment.  I'm not sure if it should
    martin> always be true.

At the functional level it should. At the UI level, the intent is
to make it a single step indeed.

    martin> Also, I have some doubts about whether we should
    martin> really have a separate 'resolve' step that means only
    martin> "I resolved it".

There are ambiguities here, when reading the doc strings and the
code, I was surprised to realized that resolve is in fact
intended to mean 'mark resolved', the command intent (today) is
to inform bzr that it should not consider the specified file(s)
as a conflict anymore.

I,'m pretty sure some users have misunderstood that to be: 'I
don't know what this conflict is about, please bzr, resolve it
for me' and ended up with .OTHER. .THIS .moved files committed by
mistake...

    martin> If the user edited the file to remove all the
    martin> conflict markers, we can tell this mechanically and
    martin> it's fairly obvious that they now consider the file
    martin> to be ok.

The text conflicts are certainly the better understood because
bzr produces a working file that isn't usable anymore, so even a
naive user will quickly get pointed at the first conflict markers
in the file by its IDE/compiler/interpreter.

    martin> I do think it's useful that the resolution can be
    martin> done in multiple steps, possibly restarting bzr or
    martin> rebooting the machine in between - it's not enough,
    martin> as bk does/did to do it all synchronously in the
    martin> merge process.

Full agreement. In case it wasn't clear, the, rather shy,
proposal here was to add --interactive to resolve but still
accept --all and the file* parameter. I.e. --interactive idea is
to:
- explain the conflict,
- propose the more common ways to resolve it,
- mark the item as resolved.

That can be used for one file, some files, all. No workflow is
imposed here.

    martin> However, I would really question whether getting
    martin> people to use bzr mv/rm manually to resolve conflicts
    martin> is a good ui.  It doesn't give enough information
    martin> about what question they're answering.

Right, so I mention the bzr commands below as a quick way to
capture the way to solve the conflict, the idea is use them
internally while presenting them in a more friendly way.

For example:

Duplicate paths
---------------

bzr made a choice

3 ways:
- bzr rm .moved (accept bzr choice)
- bzr mv .moved <item> (refuse bzr choice)
- manually combine <item> and .moved

resolve:
- delete .moved if still present ? (not done so far ?)

bzr resolve --interactive <item>
<base> is <revid>/<revno>
<other> wants to create <item> bzr created <item>.moved
<this> keeps <item>
1) Right, get rid of .moved
2) Wrong, .moved is the good one, get rid of <item>
3) Abort, let me handle that myself.
4) Do nothing, just mark as resolve

    martin> We'd want to also keep a non-interactive command line
    martin> interface to do these changes for the use of things
    martin> like emacs.

Well, except for better explanations, we already have that don't
we ?

<snip/>

    martin> Arguably merge should optionally take you straight
    martin> into this.

I don't really share that feeling, it seems to contradict your will to 

    martin> It seems like following this point you're making a
    martin> list of the different types of conflicts.

Not only. I indeed take the list of known conflicts and mention
what actions can be proposed to the user and what needs to be
done to cleanup when the user tell us he's done with the conflict
resolution.

May be you can re-read the list of conflicts with that
explanation in mind ? I'll appreciate feedback about what actions
should be proposed to the user.

    martin> +Text conflicts:
    martin> +---------------
    martin> +
    martin> +3 ways:
    martin> +- force THIS
    martin> +- force OTHER
    martin> +- manually solve each conflicted region
    martin> +
    martin> +resolve:
    martin> +- delete .THIS, .OTHER, .BASE  if present
    martin> +
    martin> +Content conflicts:
    martin> +------------------

    martin> How is this different?  Content conflicts for
    martin> directories or symlinks?

See bzrlib/help_topics/en/conflicts.txt, part of that list is
intended to be added here once fully defined.

    martin> Another kind of conflict (which may fit into one of
    martin> your categories) is deletion of a directory
    martin> containing unversioned files.

That's 'Deleting Parent' below I think.

    martin> If you search the bug tracker you may find some
    martin> further interesting cases.

Thanks for the feedback,

       Vincent