diff docs/troubles-handling.rst @ 5492:76963e896ea6

unstable-list: some cleanup

--- a/docs/troubles-handling.rst	Wed Aug 26 12:39:47 2020 +0200
+++ b/docs/troubles-handling.rst	Mon Aug 17 13:47:52 2020 +0530
@@ -10,7 +10,7 @@
 
 This document is intended for developer of the changeset evolution concept. It
 cover through the technical aspects of each "instability" a changeset can get
-into. A aims at building an exhaustive list of each cases and sub-cases and the
+into. It aims at building an exhaustive list of each cases and sub-cases and the
 status of automatic resolution for these cases.
 
 Public changeset are part of the permanent history and are never considered
@@ -33,7 +33,7 @@
 Cause of trouble
 ****************
 
-Orphan can appears because the use locally rewrite changeset with descendants.
+Orphan can appears because the user locally rewrite changeset with descendants.
 In this case the orphan are created when the command run.
 
 Orphan can also happens when the users created new changeset on draft that got
@@ -53,7 +53,8 @@
 * obsolete parent could have been prune, so it has not direct successors,
 * obsolete parent was split in multiple changesets. This comes with multiple
   variants:
-  * successors could be linear of spread accross multiple branches,
+
+  * successors could be linear of spread across multiple branches,
   * successors could have been reordered after the initial split,
   * Some of the successors could have been pruned.
 * the orphan changeset can be a merge and orphan may come any numbers of parents
@@ -79,7 +80,7 @@
 Current Support Level
 """""""""""""""""""""
 
-Good: current implementation is expected to perform the planed stabilisation.
+Good: current implementation is expected to perform the planned stabilisation.
 
 O-A2: parent is pruned (no successors)
 --------------------------------------
@@ -88,7 +89,7 @@
 Stabilisation Strategy
 """"""""""""""""""""""
 
-find nearest "not-pruned" ancestor  and treat it (or its successor, if apply) as
+Find nearest "not-pruned" ancestor and treat it (or its successor, if apply) as
 a resolution parent. (re-run Orphan resolution starting from these parent).
 
 XXX what about if they are multiple heads to that set of "not-pruned" ancestor?
@@ -97,11 +98,12 @@
 Current Support Level
 """""""""""""""""""""
 
-Good support if there they are only one head to the set
+Good support if there is only one head to the set.
 
 O-A3: parent has multiple successors sets
 -----------------------------------------
 
+
 Stabilisation Strategy
 """"""""""""""""""""""
 
@@ -111,40 +113,36 @@
 O-A4: parent is split into multiple successors
 ----------------------------------------------
 
-O-A4.1: parent are all one the same topological branch
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+O-A4.1: successors of parent are all one the same topological branch
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 
 Stabilisation Strategy
 """"""""""""""""""""""
-pick highest one as resolution  parent if all the succs are in a single topo branch
+
+Pick highest one as resolution parent.
 
 Current Support Level
 """""""""""""""""""""
 
-O-A4.2: parent is split into multiple successors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Good: current implementation is expected to perform the planned stabilisation.
 
-In this case, the destination can be ambiguous
+O-A4.2: parent is split into multiple topological branches (at least 2 heads)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In this case, the destination can be ambiguous.
 
 Stabilisation Strategy
 """"""""""""""""""""""
 
-prompt user to choose one
+prompt user to choose one.
 
 (could we do better in some case?)
 
 Current Support Level
 """""""""""""""""""""
 
-
-Stabilisation Strategy
-""""""""""""""""""""""
-, otherwise   prompt user to choose one       
-
-
-
-Current Support Level
-"""""""""""""""""""""
+Current implementation is expected to perform the planned stabilisation.
 
 O-M: Parent are Merge (multiple parent)
 =======================================
@@ -153,7 +151,7 @@
 ---------------------------------
 
 XXX Simple case are probably as good as any `O-A` case. However special case are
-probably ignored right now (eg: successors of the obsolete parent is linear with
+probably ignored right now (e.g: successors of the obsolete parent is linear with
 the other parent).
 
 O-M2: both parent are obsolete
@@ -188,9 +186,9 @@
 changeset have some predecessors in common without the situation being the
 result of a split.
 
-To stabilise the situation, we need to "merge" the change introduced in each
-side of the divergence and create a new changeset, that will superceed both the
-of unstable one. The merged information can we both about file content and
+To stabilise the situation, we need to "merge" the changes introduced in each
+side of the divergence and create a new changeset, that will supersede both of
+the unstable one. The merged information can be both about file content and
 metadata (author, parent, etc).
 
 In practice there are a lot of corner case where this is "not that simple".
@@ -211,7 +209,7 @@
 * if divergent changesets moved, check which side moved in which direction,
   and proceed accordingly
 * they moved on different unrelated branches
-* divergent changesets is orphan
+* divergent changeset can be orphan as well
 * one side of divergence is in public phase
 
 Details of Sub cases