diff -r e33990a4c27a -r cbc370d6ec30 docs/evolve-collaboration.rst --- a/docs/evolve-collaboration.rst Thu Apr 23 08:35:38 2015 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,135 +0,0 @@ -.. Copyright 2011 Pierre-Yves David -.. Logilab SA - ------------------------------------------------- -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' checkpoint -initially):: - - $ 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: 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 --public - -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). - -During the transition from older Mercurial servers to new ones, this will -happen often, so be careful. - -Now let's come back to our patch. Next hour sees good progress and Alice -wants to complete the patch with the recent stuff (all that's shown by -an "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: this -is just like "hg qrefresh -m"). - -Before leaving, let's push to the central shared repository. That will -give Bob 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, Bob, who arrives very early, can immediately work out -some 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 the -next two hours:: - - $ hg pull - -Then:: - - $ hg up "tip ~ 2" - -brings her to yesterday's patch. Indeed the patch serial number has -increased (827 still exists but has been obsoleted). - -She understands that her 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 Alice installed the mutable-history extensions, she got an alias -that 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. - -* odiff - - -Amend ... Stabilize --------------------- - -Almost perfect! Alice 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 Bob. - -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 typed out? - -Alice for one, wouldn't want to merge each time she amends something that -might conflict with the descendant changesets. Remember she is -currently updating the very middle of an history! - -Being now done with grammar and typo fixes, Alice decides it is time to -stabilize again the tree. She does:: - - $ hg evolve - -two times, one for each unstable descendant. The last time, hgview -shows her a straight line again. Wow! that feels a bit like a -well-planned surgical operation. At the end, the patient tree has -been properly trimmed 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), unrecoverable operation, and the "evolve + obsolete" -combo, using changeset copy and obsolescence marker, provides evolution -semantics by only adding new information to the repository (but more -on that later). - -She pushes again. -