diff docs/evolve-collaboration.rst @ 189:e7d7201e79ce

follow-up on evolve-collaboration

--- a/docs/evolve-collaboration.rst	Wed Mar 28 11:24:30 2012 +0200
+++ b/docs/evolve-collaboration.rst	Wed Mar 28 11:18:50 2012 +0200
@@ -47,7 +47,7 @@
 The next day, Mr C.W., who arrives very early, can immediately
 work out some glitches in the patch.
 
-He then starts another one, for ticket #43 and finally commits it.
+He then starts two other, for ticket #43 and #44 and finally commits them.
 Then, as original worker arrives, he pushes his stuff.
 
 M W., now equipped with enough properly sugared coffee to survive the
@@ -57,7 +57,7 @@
 
 Then::
 
-    $ hg up "tip ~ 1"
+    $ hg up "tip ~ 2"
 
 brings him to yesterday's patch. Indeed the patch serial number has
 increased (827 still exists but has been obsoleted).
@@ -78,4 +78,55 @@
 * odiff
 
 
+Amend ... Stabilize
+--------------------
 
+Almost perfect ! W. just needs to fix a half dozen grammar oddities in
+the new docstrings and it will be publishable.
+
+Then, another round of:
+
+    $ hg amend
+
+and a quick look at hgview ... shows something strange (at first).
+
+Ticket #42 yesterday's version is still showing up, with two descendant lineages:
+
+* the next version, containing grammar fixes,
+
+* the two stacked changesets for tickets #43 .. 44 committed by C.W.
+
+Indeed, since this changeset still has non-obsolete descendant
+changesets it cannot be hidden. This branch (old version of #42 and
+the two descendants by C.W.) is said to be _unstable_.
+
+Why would one want such a state ? Why not auto-stabilize each time "hg
+amend" is spelt ?
+
+W. for one, wouldn't want to merge each time he amends something that
+might conflict with the descendant changesets; remember he is
+currently updating the very middle of an history !
+
+Being now done with grammar and typo fixes, W. decides it is time to
+stabilize again the tree. He:
+
+    $ hg stabilize
+
+two times, one for each unstable descendant. The last time, hgview
+shows him a straight line again. Wow ! that feels a bit like a
+well-planned surgical operation. At the end, the patient^Wtree has
+been properly sewed and any conflict properly handled.
+
+Of course nothing fancy really happened: each "stablilize" can be
+understood in terms of a rebase of the next unstable descendant to the
+newest version of its parent (including the possible manual conflict
+resolution intermission ...).
+
+Except that rebase is a destructive (it removes information from the
+repository), unexchangeable operation, and the "evolve + obsolete"
+combo, using changeset copy and obsolescence marker, provide evolution
+semantics by only adding new information to the repository (but more
+on that later).
+
+He pushes again.
+