notes/tree-conflicts/requirements.txt

Status of this file: In progress.

Purpose of the file: To record the requirements and principles that guide the design of tree-conflict handling. ("Policy" is not a good name for it.)


BACKGROUND AND TERMINOLOGY
==========================

MERGE TRACKING
--------------

The merge tracking feature helps the client software to determine which changes
(revisions) from the source branch to apply to the specified target tree. After
that has been determined, the application of one change to one target is where
conflict detection becomes involved.

At this level of applying changes to the target, merge tracking is irrelevant.

MERGE IS DIFF-AND-APPLY
-----------------------

Subversion's definition of "merging" is to determine the difference between two
source trees SOURCE-LEFT and SOURCE-RIGHT, and try to apply that difference to
a TARGET tree. The diff that it tries to apply is an arbitrary low-level
representation of the overall difference between SOURCE-LEFT and SOURCE-RIGHT,
not the series of logically meaningful transformations by which the user
originally transformed SOURCE-LEFT into SOURCE-RIGHT.

Typically, SOURCE-LEFT is an ancestor of SOURCE-RIGHT in a source branch, but
this need not be so. (One effect of the "--ignore-ancestry" option is to force
the merge to perform a detailed diff between the sources even if they are not
so related, where it would otherwise present the diff as "delete SOURCE-LEFT;
add SOURCE-RIGHT".)

The differences are applied to a working copy of the TARGET tree (which may
include some local modifications against its base).

The degree of success of a merge depends on the degree to which the TARGET tree
is similar enough to SOURCE-LEFT for Subversion to be able to match each file
or directory involved in the diff to a corresponding file or directory in
TARGET. This matching is done purely by path. Where this matching fails, the
merge cannot apply that part of the diff. Some of these failures will be
defined as "tree conflicts".


USE CASES
=========

The use cases (in "use-cases.txt") illustrate some of the cases that are to be
handled, but are not a complete set of requirements.

The user-level requirements are presented in terms of user-interface actions.
Note that the design is formulated and presented in terms of lower-level
operations that do not include a "rename" operation.


REQUIREMENTS
============

These requirements specify what a tree conflict means, how a tree conflict
behaves, and under exactly what conditions a tree conflict is raised. These
requirements are intended to apply in all merge, switch and update commands
unless otherwise stated.

DEFINITION OF A TREE CONFLICT
-----------------------------

A conflict is the condition that occurs when Subversion cannot apply a source
change correctly and with certainty to a corresponding target object. A tree
conflict is a kind of conflict that occurs due to a part of the TARGET tree
being in some sense "incompatible" with the SOURCE-LEFT tree in kind, name,
location, absence or presence.

Every tree conflict shall be signaled both by an indication when the conflict
occurs and by being marked in the WC in a way that shows up as a conflict in
the "svn status" output.

The state of conflict shall persist until the user confirms that it has been
resolved. The user shall be able to confirm the resolution of each and every
conflict individually, and shall also be able to confirm the resolution of all
conflicts in a tree with a single command.

Confirming the resolution of each and every tree conflict means being
able to confirm the resolution of a tree conflict with a single tree conflict
victim, even though there might be more than one tree conflict victim
in a directory. A tree conflict victim is a file or directory in the tree
which is affected by a tree conflict. For example, it might be a file
which is deleted during an update operation while carrying local modifications,
or it might be a file being blocked during a merge by an unversioned file of
the same name. Each tree conflict has only a single victim.

Every condition that results in the source diff not being fully applied to the
target shall result in either a conflict or an error exit, with a strong
preference for a conflict.

CONSEQUENCES OF A TREE CONFLICT
-------------------------------

A commit shall be disallowed if any item considered as part of the commit is
marked with a conflict (a tree conflict or any other conflict).

A merge or switch or update shall be disallowed if it affects a part of the WC
that is marked with a conflict.

NON-REQUIREMENTS
----------------

It is desirable for a tree conflict to be resolved automatically (and thus not
to be signaled as a conflict) when there is a way to do so that is clearly what
the user wants. This might require some configurable rules. This is not
presently a requirement.

FAILURE TO GENERATE THE DIFF
----------------------------

When the diff cannot be completely determined due to read access restrictions
in the source repository, tree conflicts shall be handled as defined herein for
those parts of the diff that are determined. Rules for whether and how to
proceed with an incomplete diff are out of scope of this tree-conflicts
document.

FAILURE TO APPLY THE DIFF
-------------------------

When a part of the diff should apply to a part of the WC that is switched, the
rule for whether to apply the diff to this switched subtree or to the natural
(unswitched) subtree or to both or to neither is out of scope of this
tree-conflicts document, but tree conflict handling shall apply wherever the
diff is applied.

When a part of the diff cannot be applied, due to not finding a corresponding
object or due to an unversioned item being present in the working copy at this
path, a conflict is to be signaled. (Previously, in some cases a conflict was
raised, in some cases a warning was issued, and in some cases the change was
silently discarded.)

When a part of the diff should apply to a part of the WC that is absent
(perhaps due to authz restrictions or due to an intentionally sparse WC), a
conflict shall be signaled. ###? This seems to be use case 4, right?

LOCAL WC MODIFICATIONS
----------------------

Correct behaviour with local WC mods in TARGET is conceptually the same as if
that uncommitted revision were just another committed revision. (Any necessary
differences are to be detailed on delivery.) Correct behaviour with local mods
is required for "update". For "switch" and "merge", correct behaviour with
local mods is desired but not required for initial delivery.

If there is already a conflict in a part of the WC that is to be affected by
the merge, then the application of the merge shall be disallowed and no part of
the WC shall be altered.

### TODO: How can users use 'svn merge' to resolve a tree conflict?

NON-CONFLICTS
-------------

When a file is to be deleted or renamed, there shall be a conflict unless the
target file is identical to the SOURCE-LEFT file. Identical shall mean
identical text and properties except for "svn:mergeinfo".

When a directory is to be deleted or renamed, there shall be a conflict unless
the target directory is identical to the SOURCE-LEFT directory. Identical shall
mean identical properties except for "svn:mergeinfo", and an identical list of
children (including their types), and recursively identical directory children
and file children according to these definitions of "identical" for directories
and for files respectively.

### Is that last test (directory being identical) too expensive/impractical to
calculate?

### This is something I've also been thinking about - determining equality
    of directories may turn out to be a major problem. Would requiring only
    the direct children to be equal be an acceptable compromise?