Rev 4600: Clarify some points to address poolie's early review. in file:///home/vila/src/bzr/experimental/conflict-manager/

[Vincent Ladeuil]

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

------------------------------------------------------------
revno: 4600
revision-id: v.ladeuil+lp at free.fr-20090813131048-c616zubedt3gl7wz
parent: v.ladeuil+lp at free.fr-20090813062135-mvkhie71vei48lco
committer: Vincent Ladeuil <v.ladeuil+lp at free.fr>
branch nick: description
timestamp: Thu 2009-08-13 15:10:48 +0200
message:
  Clarify some points to address poolie's early review.
-------------- next part --------------
=== modified file 'Outline.txt'
--- a/Outline.txt	2009-08-13 06:21:35 +0000
+++ b/Outline.txt	2009-08-13 13:10:48 +0000
@@ -1,18 +1,39 @@
+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
+
+
+Overall presentation:
+=====================
+
 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
+their occurrence, as is 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.
+``bzr`` try to avoid conflicts, its aim is to ask the user to
+resolve the conflict if and only if there's an actual conceptual
+conflict in the source tree.  Because bzr doesn't understand the
+real meaning of the files being versioned it can fall short in
+either direction trying to resolve the conflict itself when faced
+with ambiguities.
 
-When it can't, it add information into the working tree to
-present the conflicting versions and leave the resolution to the
-user.
+When it can't resolve, bzr 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:
 
@@ -34,6 +55,36 @@
 display a short explanation of the conflict and propose some
 actions before marking the file as resolved.
 
+
+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.
+
+The --all and file* parameters will still be honored so that the
+user solve conflicts at his own pace.
+
+It should be possible for a GUI to query the conflict objects for
+possible actions (in textual form) and trigger them.
+
+
+Proposed actions by conflict type:
+==================================
+
+The following paragraphs list all the existing conflict types and summarize:
+- the actions that can be proposed to the user,
+- the cleanups that could remain to be done once the conflict is solved,
+
+In practice, the actions will always contain:
+- leave the user solve the conflict by its own means,
+- mark the conflict as solved without any additional action.
+
+
 Text conflicts:
 ---------------
 
@@ -159,28 +210,3 @@
 
 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
-