.. Copyright 2011 Pierre-Yves David <pierre-yves.david@ens-lyon.org>.. Logilab SA <contact@logilab.fr>------------------------------------------------Collaboration Using Evolve: A user story------------------------------------------------After having written some code for ticket #42, Alice starts a patch(this will be kind of like a 'work-in-progress' checkpointinitially):: $ hg 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: draftSee? Until the day it becomes a "public" changeset, this can bealtered to no end. How? It happens with an explicit:: $ hg phase --publicIn practice, pushing to a "publishing" repository can also turn draftchangesets into public ones. Older Mercurial releases are automatically"publishing" since they do not have the notion of non-public changesets(or mutable history).During the transition from older mercurial servers to new ones, this willhappen often, so be careful.Now let's come back to our patch. Next hour sees good progress and Alicewants to complete the patch with the recent stuff (all that's shown byan "hg diff") to share with a co-worker, Bob:: $ hg amend -m '[entities] fix frobulator (closes #42)'Note that we also fix the commit message. (For recovering mq users: thisis just like "hg qrefresh -m").Before leaving, let's push to the central shared repository. That willgive Bob the signal that something is ripe for review / further amendments:: $ hg push # was done with a modern mercurial, draft phase is preservedThe next day, Bob, who arrives very early, can immediately work outsome glitches in the patch.He then starts two others, for ticket #43 and #44 and finally commits them.Then, as original worker arrives, he pushes his stuff.Alice, now equipped with enough properly sugared coffee to survive thenext two hours:: $ hg pullThen:: $ hg up "tip ~ 2"brings her to yesterday's patch. Indeed the patch serial number hasincreased (827 still exists but has been obsoleted).She understands that his original patch has been altered. But how did itevolve?The enhanced hgview shows the two patches. By default only the mostrecent version of a patch is shown.Now, when Alice installed the mutable-history extensions, she got an aliasthat allows her to see the diff between two amendments, defined like this:: odiff=diff --rev 'limit(obsparents(.),1)' --rev .She can see exactly how Bob amended her work.* odiffAmend ... Stabilize--------------------Almost perfect ! Alice just needs to fix a half dozen grammar oddities inthe new docstrings and it will be publishable.Then, another round of: $ hg amendand 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 Bob.Indeed, since this changeset still has non-obsolete descendantchangesets it cannot be hidden. This branch (old version of #42 andthe two descendants by C.W.) is said to be _unstable_.Why would one want such a state? Why not auto-stabilize each time "hgamend" is typed out?Alice for one, wouldn't want to merge each time she amends something thatmight conflict with the descendant changesets. Remember she iscurrently updating the very middle of an history!Being now done with grammar and typo fixes, Alice decides it is time tostabilize again the tree. She does:: $ hg evolvetwo times, one for each unstable descendant. The last time, hgviewshows her a straight line again. Wow! that feels a bit like awell-planned surgical operation. At the end, the patient tree hasbeen properly trimmed and any conflict properly handled.Of course nothing fancy really happened: each "stablilize" can beunderstood in terms of a rebase of the next unstable descendant to thenewest version of its parent (including the possible manual conflictresolution intermission ...).Except that rebase is a destructive (it removes information from therepository), unrecoverable operation, and the "evolve + obsolete"combo, using changeset copy and obsolescence marker, provide evolutionsemantics by only adding new information to the repository (but moreon that later).She pushes again.