Re: [RFC] new svn_client_conflict API

Hi, Stefan. Glad to see this!

Changing the API syntactic form to an opaque struct + accessor
functions sounds fine, as I mentioned on IRC. I see you've done that
already.

As for the semantic changes, I want to help clarify our understanding
of the high level 'shape' of merge scenarios. We need clear conceptual
model in mind, in order to be able to suggest an understandable UI for
merge conflicts.

(We must continually be on the look out for conceptually simple ways
to understand the system, and never accept that it has to be complex
beyond understanding.)

I've drawn a picture. The attached diagram 'merge corners 2.png' shows
two branches, B1 and B2; let's say they are branch root directories,
and they have children which are not shown. B2_at_60 is checked out into
a WC. We are merging r30:50 from B1 to the WC.

If this is an automatic merge, then B1_at_30 is the youngest common
ancestor, both in reality and in what we tell the 3-way merge
algorithm. That is true because an automatic merge requires that
r10:30 from B1 is already merged to the target.

Otherwise, this is a cherry-pick merge; B1_at_30 is an *assumed* common
ancestor for the 3-way merge algorithm, while B1_at_10 is the *real*
youngest common ancestor. Note that if we chose to use a 4-way merge
algorithm for cherry-pick merges, aka 'variance-adjusted patching',
such as the one implemented in our 'tools/diff/diff4', then we would
pass it both the real YCA = B1_at_10 and also the source-left B1_at_30, as
well as source-right and target.

The three points marked in red (B1_at_30, B1_at_50, WC_at_working) are the main
input 'corners' of the 3-way merge. Other revisions of interest are
the WC base and the true YCA B1_at_10. The main point I want to make is
that the WC base is not a high-level input to the merge. Rather, it is
a point in the practical work flow that has to be negotiated to get to
the desired logical endpoint (the WC working state).

So where does this take us?

I believe it's helpful to see two categories of conflicts:

  * conflicts between the two sets of version-controlled changes --
that is, the kinds of changes supported by the repository

  * inconsistent WC state -- for example, no file actually on disk
where the working state metadata says there is a file, etc. (I don't
even like to call these 'conflicts')

Conflicts in category (1) are a result of the logical high-level merge
operation. They are exactly the same conflicts that could occur if we
were to implement an option to perform the merge on the server writing
its result directly into a commit transaction. The most relevant data,
in my opinion, are the three "corners" of the 3-way merge, followed
next by the real YCA if different from source-left, and finally
followed by the WC base state.

The category (2) 'conflicts', on the other hand, are absolutely
related to the WC state. The WC base state and working state are
pretty much the only thing that needs to be shown. The merge itself is
merely the reason why we found this inconsistency in the WC -- the
merge is not the primary interesting thing about these.

Thus, a conflict with reason 'svn_wc_conflict_reason_unversioned' for
example is in category (2).

By keeping these two categories conceptually separated, we can provide
a clearer view of the relevant information.

(Another thing I notice about the 'action' and 'reason' descriptions
is they're documented as applying to an 'object' -- 'Object is
unversioned', for example. The current merge system, and thus the
conflict system, is mainly based on paths. In any tree change, one
'object' does not map cleanly to one path. This is a source of
confusion.)

Does that help a bit?

- Julian

Stefan Sperling wrote:
> I would like to start transitioning away from svn_wc_conflict_description2_t
> in public APIs and introduce a higher-level API to eventually replace it.
[...]
> Below is a sketch of an API I'd like to wrap around the
> svn_wc_conflict_description2_t struct.
>
> The API uses terminology that I'd like clients to mirror in their user
> interfaces. It breaks with some naming conventions that are misleading
> or insufficient to describe complex conflicts (e.g. "yours/mine/theirs").
> It also tries to explain things in a way that prevents misunderstandings
> of what the information returned by the API really means, so that SVN
> client authors can make informed choices about how to present the information.
>
> The intention is to later extend this API to produce detailed data about
> tree conflicts and other complex scenarios so that users can make more
> informed choices about how to resolve conflicts.
> See http://mail-archives.apache.org/mod_mbox/subversion-users/201505.mbox/%3C20150520105235.GE4388%40jim.stsp.name%3E
> for an example of what I'd eventually like to see at the conflict prompt.
[...]