# HG changeset patch # User Pierre-Yves David # Date 1598443749 -7200 # Node ID c408a31d8883839be5af3152a921f60f49ff071f # Parent c7a5133e4a7c2034ef324985731a869f2dc89ab6 unstable-list: fix title level diff -r c7a5133e4a7c -r c408a31d8883 docs/troubles-handling.rst --- a/docs/troubles-handling.rst Wed Aug 26 13:07:57 2020 +0200 +++ b/docs/troubles-handling.rst Wed Aug 26 14:09:09 2020 +0200 @@ -1,6 +1,6 @@ ------------------------------------------------------------ +########################################################### Possible troubles in rewriting history and their resolution ------------------------------------------------------------ +########################################################### .. Copyright 2020 Sushil Khanchi .. Octobus SAS @@ -19,11 +19,12 @@ .. contents:: :depth: 4 +****** Orphan -######### +****** Basics -****** +====== A changeset is orphan when there is at least one obsolete ancestor. @@ -34,7 +35,7 @@ "stabilised" fist. Cause of trouble -**************** +================ Orphan can appears because the user locally rewrite changeset with descendants. In this case the orphan are created when the command run. They are few real use @@ -46,7 +47,7 @@ This is the most common way to create phase divergences. Source of Complexity -******************** +==================== There can be different situations we need to take care of when dealing with resolution of an orphan changeset, like: @@ -66,36 +67,33 @@ * rebasing might lead to conflict. Details of Sub cases -******************** +==================== .. contents:: :local: O-A: Linear changeset (one parent) -================================== +---------------------------------- O-A1: parent has a single successors ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Stabilisation Strategy -"""""""""""""""""""""" +**Stabilisation Strategy** Solution is Clear. Relocate the orphan changeset onto the single successor of obsolete parent. -Current Support Level -""""""""""""""""""""" +**Current Support Level** Good: current implementation is expected to perform the planned stabilisation. O-A2: parent is pruned (no successors) --------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Stabilisation Strategy -"""""""""""""""""""""" +**Stabilisation Strategy** 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). @@ -103,75 +101,69 @@ XXX what about if they are multiple heads to that set of "not-pruned" ancestor? Especially when they are more then 2 ? -Current Support Level -""""""""""""""""""""" +**Current Support Level** Good support if there is only one head to the set. O-A3: parent has multiple successors sets ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Stabilisation Strategy -"""""""""""""""""""""" +**Stabilisation Strategy** -Current Support Level -""""""""""""""""""""" +**Current Support Level** O-A4: parent is split into multiple successors ----------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ O-A4.1: successors of parent are all one the same topological branch -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -Stabilisation Strategy -"""""""""""""""""""""" +**Stabilisation Strategy** Pick highest one as resolution parent. -Current Support Level -""""""""""""""""""""" +**Current Support Level** Good: current implementation is expected to perform the planned stabilisation. O-A4.2: parent is split into multiple topological branches (at least 2 heads) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" In this case, the destination can be ambiguous. -Stabilisation Strategy -"""""""""""""""""""""" +**Stabilisation Strategy** prompt user to choose one. (could we do better in some case?) -Current Support Level -""""""""""""""""""""" +**Current Support Level** Current implementation is expected to perform the planned stabilisation. O-M: Parent are Merge (multiple parent) -======================================= +--------------------------------------- O-M1: Only one parent is obsolete ---------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ XXX Simple case are probably as good as any `O-A` case. However special case are probably ignored right now (e.g: successors of the obsolete parent is linear with the other parent). O-M2: both parent are obsolete ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ XXX currently we evolve one after the other. +**************** Phase-Divergence -################## +**************** Basics -****** +====== It appears when a rewritten changeset got published. A phase-divergent changeset @@ -182,7 +174,7 @@ changesets, descendants of the public prédecessors. Cause of trouble -**************** +================ It can appear if a user locally change the phase of an obsolete changeset (which has successors) to public. @@ -192,7 +184,7 @@ publishing information of the predecessors is pulled in the local repository. Source of Complexity -******************** +==================== * public version is a merge * phase-divergent changeset is a merge @@ -201,18 +193,19 @@ * rebasing might lead to conflict. Details of Sub cases -******************** +==================== .. contents:: :local: #TODO: yet to document +****************** Content-Divergence -################## +****************** Basics -****** +====== Independent rewrites of same changeset leads to content-divergence. So an @@ -228,7 +221,7 @@ In practice there are a lot of corner case where this is "not that simple". Cause of trouble -**************** +================ It can appear locally if a user independently rewrite the same changeset multiple times. @@ -238,7 +231,7 @@ when the rewriting information is shared (pulled/pushed) with another repository. Source of Complexity -******************** +==================== Before we perform a 3-way merge between the divergent changesets and common @@ -251,7 +244,7 @@ * one side of divergence is in public phase Details of Sub cases -******************** +==================== .. contents:: :local: