Rev 4599: First draft describing the different conflicts and some ways to resolve them. in file:///home/vila/src/bzr/experimental/conflict-manager/

[Vincent Ladeuil]

At file:///home/vila/src/bzr/experimental/conflict-manager/

------------------------------------------------------------
revno: 4599
revision-id: v.ladeuil+lp at free.fr-20090813062135-mvkhie71vei48lco
parent: v.ladeuil+lp at free.fr-20090813061932-ia102mjscytelufh
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: description
timestamp: Thu 2009-08-13 08:21:35 +0200
message:
  First draft describing the different conflicts and some ways to resolve them.
-------------- next part --------------
=== added file 'Outline.txt'
--- a/Outline.txt	1970-01-01 00:00:00 +0000
+++ b/Outline.txt	2009-08-13 06:21:35 +0000
@@ -0,0 +1,186 @@
+When conflicts are present in a working tree (as shown by ``bzr
+conflicts``), the user should resolve them and then inform bzr
+that the conflicts has been resolved.
+
+Resolving conflicts is sometimes not obvious. Either because the
+user that should resolve them is not the one responsible for
+their occurrence, as it's the case when merging other people work
+or because some conflicts are presented in a way that is not easy
+to understand.
+
+``bzr`` try to avoid conflicts.
+
+When it can't, it add information into the working tree to
+present the conflicting versions and leave the resolution to the
+user.
+
+Whatever the conflict is, resolving it is roughly done in two steps:
+
+- modify the working tree content so that the conflicted item is
+  now in the desired state, there are,
+
+- inform bzr that the conflict is now solved and ask to cleanup
+  any remaining generated information (``bzr resolve <item>``).
+
+
+For most conflict types, there are some obvious ways to modify
+the working tree and put it into the desired state. For some type
+of conflicts, bzr itself already made a choice when possible.
+
+Yet, whether bzr made a choice or not, there are some other ways
+simple but alternative ways to resolve the conflict.
+
+Providing the ``--interactive`` option to ``bzr resolve`` will
+display a short explanation of the conflict and propose some
+actions before marking the file as resolved.
+
+Text conflicts:
+---------------
+
+3 ways:
+- force THIS
+- force OTHER
+- manually solve each conflicted region
+
+resolve:
+- delete .THIS, .OTHER, .BASE  if present
+
+Content conflicts:
+------------------
+
+3 ways:
+- bzr mv .THIS <item>,
+- bzr mv .OTHER <item>,
+- manually combine .THIS and .OTHER
+
+resolve:
+- delete .THIS, .OTHER, .BASE if present
+
+
+Duplicate paths
+---------------
+
+bzr made a choice
+
+3 ways:
+- bzr mv .moved <item> (refuse bzr choice)
+- bzr rm .moved (accept bzr choice)
+- manually combine <item> and .moved
+
+resolve:
+- delete .moved if still present ? (not done so far ?)
+
+
+Unversioned parent
+------------------
+
+bzr made a choice: version the parent
+
+3 ways:
+- bzr rm <children>
+- bzr rm <parent>
+- manually rename <children>
+
+resolve:
+- nothing to do ?
+
+XXX: need investigation to enumerate all cases
+
+
+Missing parent
+--------------
+
+bzr made a choice: create the missing parent and version it.
+
+3 ways:
+- bzr rm <children>
+- bzr rm <parent>
+- manually rename <children>
+
+resolve:
+- nothing to do ?
+
+XXX: need investigation to enumerate all cases
+
+
+Deleting parent
+---------------
+
+bzr made a choice: not delete the parent
+
+3 ways:
+- bzr rm <children>
+- bzr rm <parent>
+- manually solve the issue (may be more than a single children)
+
+resolve:
+- nothing to do
+
+
+Path conflict
+-------------
+
+bzr made a choice: use the source's name
+
+3 ways:
+- do nothing (accept bzr choice)
+- bzr mv <item> other-name (refuse bzr choice)
+- manually rename to a different name
+
+resolve:
+- nothing to do 
+
+Parent loop
+-----------
+
+bzr made a choice: keep the existing renaming
+
+3 ways:
+- do nothing (accept bzr choice)
+- bzr mv this_parent/this_children other_parent/other_children
+- manually rename the items
+
+resolve:
+- nothing to do
+
+
+Non-directory parent
+--------------------
+
+bzr made a choice: create a <parent>.new directory
+
+There is no obvious single action that can solve the conflict
+here, but let's try anyway.
+
+3 ways:
+- bzr rm <parent>.new
+- bzr rm <parent> + bzr mv <parent>.new <parent>
+- manually rename the items
+
+resolve:
+- nothing to do
+
+Design:
+=======
+
+The Conflict classes will receive additional methods to resolve
+the conflict in alternative ways.
+
+Resolve will receive a ``--interactive`` option and present a
+list of possible actions (including do nothing) to the user
+before marking the file as resolved.
+
+It should be possible for a GUI to query the conflict objects for
+possible actions (in textual form) and trigger them.
+
+TODO:
+
+- add more info to Conflict objects:
+  - 
+  - base revid for text conflict
+
+- tests with '.diverted' files ?
+
+- doc/es/user-guide/resolving_conflicts.txt is really
+  use-reference/resolving_conflicts.txt
+