--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/evolve-collaboration.rst	Tue Mar 27 16:55:47 2012 +0200
@@ -0,0 +1,81 @@
+
+------------------------------------------------
+Collaboration Using Evolve: A user story
+------------------------------------------------
+
+
+After having written some code for ticket #42, M W. start a patch (this
+will be kind of like a 'work-in-progress' checkpoint initially)::
+
+    $ ci -m '[entities] remove magic'
+
+Instant patch ! Note how the default phase of this changeset is (still)
+in "draft" state.
+
+This is easily checkable::
+
+    $ hg phase tip
+    827: draft
+
+See ? Until the day it becomes a "public" changeset, this can be altered
+to no end. How ? It happens with an explicit::
+
+    $ hg phase -p
+
+In practice, pushing to a "publishing" repository can also turn draft
+changesets into public ones. Older mercurial releases are automatically
+"publishing" since they do not have the notion of non-public changesets
+(or mutable history).
+
+In the transition ... phase from older mercurial servers, this will
+happen often, so be careful.
+
+Now let's come back to our patch. Next hour sees good progress and W.
+wants to complete the patch with the recent stuff (all that's shown by
+an "hg diff") to share with a co-worker (let's call him C.W.)::
+
+    $ hg amend -m '[entities] fix frobulator (closes #42)'
+
+Note that we also fix the commit message. (For recovering mq users: this
+is just like "hg qrefresh -m").
+
+Before leaving, let's push to the central shared repository. That will
+give C.W. the signal that something is ripe for review / further amendments::
+
+    $ hg push # was done with a modern mercurial, draft phase is preserved
+
+The next day, Mr C.W, which arrives very very early, can immediately
+work out some glitches in the patch.
+
+He then starts another one, for ticket #43 and finally commits it.
+Then, as original worker arrives, he pushes his stuff.
+
+M W., now equipped with enough properly sugared coffee to survive the
+next two hours::
+
+    $ hg pull
+
+Then::
+
+    $ hg up "tip ~ 1"
+
+brings him to yesterday's patch. Indeed the patch serial number has
+increased (827 still exists but has been obsoleted).
+
+He understands that his original patch has been altered. But how did it
+evolve ?
+
+The enhanced hgview shows the two patches. By default only the most
+recent version of a patch is shown.
+
+Now, when W. installed the mutable-history extensions, he got an alias
+that allows him to see the diff between two amendments, defined like this::
+
+    odiff=diff --rev 'limit(obsparents(.),1)' --rev .
+
+He can see exactly how C.W. amended his work.
+
+* odiff
+
+
+

--- a/docs/index.rst	Tue Mar 27 16:50:14 2012 +0200
+++ b/docs/index.rst	Tue Mar 27 16:55:47 2012 +0200
@@ -79,6 +79,7 @@
    tutorial
    evolve-faq
    from-mq
+   evolve-collaboration
 
 Smart changeset deletion: Obselete Marker
 ==========================================