# HG changeset patch # User Greg Ward # Date 1403266744 14400 # Node ID 33ed6119a0bec7168c06f55380170e97561f3ece # Parent eb0a1d1d499b3339b874667158df36f9edd9665f docs (sharing): more scattered wording tweaks diff -r eb0a1d1d499b -r 33ed6119a0be docs/sharing.rst --- a/docs/sharing.rst Tue Apr 14 12:55:04 2015 -0400 +++ b/docs/sharing.rst Fri Jun 20 08:19:04 2014 -0400 @@ -289,12 +289,21 @@ mutable history with others. It does, but you have to be careful, stay alert, and *communicate* with your peers. -A good way to start is with code review: Alice commits a draft -changeset that Bob can review. Bob sends his comments to Alice, and -she amends it until Bob is satisfied. Meanwhile, Bob is also -committing draft changesets for Alice to review, amending until she is -satisfied. Once a particular changeset passes review, the respective -author (Alice or Bob) pushes it to the public repository. +Code review is a good use case for sharing mutable history across +multiple developers: Alice commits a draft changeset, submits it for +review, and amends her changeset until her reviewer is satisfied. +Meanwhile, Bob is also committing draft changesets for review, +amending until his reviewer is satisfied. Once a particular changeset +passes review, the respective author (Alice or Bob) pushes it to the +public (publishing) repository. + +Incidentally, the reviewers here can be anyone: maybe Bob and Alice +review each other's work; maybe the same third party reviews both; or +maybe they pick different experts to review their work on different +parts of a large codebase. Similarly, it doesn't matter if reviews are +conducted in person, by email, or by carrier pigeon. Code review is +outside of the scope of Mercurial, so all we're looking at here +is the mechanics of committing, amending, pushing, and pulling. Setting up ========== @@ -314,9 +323,8 @@ updating to branch default 1 files updated, 0 files merged, 0 files removed, 0 files unresolved -We need to configure Alice's and Bob's working repositories similar to -``test-repo``, i.e. make them non-publishing and enable ``evolve``. -First, edit Alice's configuration with :: +We need to configure Alice's and Bob's working repositories to enable +``evolve``. First, edit Alice's configuration with :: $ hg -R alice config --edit --local @@ -325,17 +333,19 @@ [extensions] evolve = /path/to/mutable-history/hgext/evolve.py -Then add the same text to Bob's repository configuration:: +Then edit Bob's repository configuration:: $ hg -R bob config --edit --local +and add the same text. + Example 3: Alice commits and amends a draft fix =============================================== -We'll start by following Alice working on a bug fix. We're going to -use bookmarks to make it easier to understand multiple branch heads in -the ``review`` repository, so Alice starts off by creating a bookmark -and committing her first attempt at a fix:: +We'll follow Alice working on a bug fix. We're going to use bookmarks to +make it easier to understand multiple branch heads in the ``review`` +repository, so Alice starts off by creating a bookmark and committing +her first attempt at a fix:: $ hg bookmark bug15 $ echo 'fix' > file2 @@ -363,10 +373,8 @@ .. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/ .. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks -Some time passes, and Alice receives her code review. (It might be by -email, telephone, or carrier pigeon: it doesn't matter, as it's -outside the scope of Mercurial.) As a result, Alice revises her fix -and submits it for a second review:: +Some time passes, and Alice receives her code review. As a result, +Alice revises her fix and submits it for a second review:: $ echo 'Fix.' > file2 $ hg amend -m 'fix bug 15 (v2)' @@ -379,21 +387,21 @@ [figure SG06: rev 2:fn1e is Alice's obsolete v1, rev 3:cbdf is her v2; both children of rev 1:de61] -After a hard morning of bug fixing, Alice stops for lunch. Let's see +After a busy morning of bug fixing, Alice stops for lunch. Let's see what Bob has been up to. Example 4: Bob implements and publishes a new feature ===================================================== -In the meantime, Bob has been working on a new feature. Like Alice, -he'll use a bookmark to track his work, and he'll push that bookmark -to the ``review`` repository, so that reviewers know which changesets -to review. :: +Meanwhile, Bob has been working on a new feature. Like Alice, he'll +use a bookmark to track his work, and he'll push that bookmark to the +``review`` repository, so that reviewers know which changesets to +review. :: $ cd ../bob $ echo 'stuff' > file1 $ hg bookmark featureX - $ hg commit -u bob -m 'implement feature X (v1)' + $ hg commit -u bob -m 'implement feature X (v1)' # rev 4:1636 $ hg push -B featureX [...] added 1 changesets with 1 changes to 1 files (+1 heads) @@ -403,7 +411,7 @@ bit, amends, and submits the resulting changeset for review:: $ echo 'do stuff' > file1 - $ hg amend -m 'implement feature X (v2)' + $ hg amend -m 'implement feature X (v2)' # rev 5:0eb7 $ hg push [...] added 1 changesets with 1 changes to 1 files (+1 heads) @@ -413,7 +421,7 @@ on proper capitalization and punctuation. :: $ echo 'Do stuff.' > file1 - $ hg amend -m 'implement feature X (v3)' + $ hg amend -m 'implement feature X (v3)' # rev 6:540b On the bright side, the second review said, "Go ahead and publish once you fix that." So Bob immediately publishes his third attempt:: @@ -422,10 +430,11 @@ [...] added 1 changesets with 1 changes to 1 files -Bob also has to update the ``review`` repository: right now it doesn't -have his latest amendment ("v3", revision 6:540b), and it doesn't know -that the precursor of that changeset ("v2", revision 5:0eb7) is -obsolete. :: +It's not enough just to update ``public``, though! Other people also +use the ``review`` repository, and right now it doesn't have Bob's +latest amendment ("v3", revision 6:540b), nor does it know that the +precursor of that changeset ("v2", revision 5:0eb7) is obsolete. Thus, +Bob pushes to ``review`` as well:: $ hg push ../review [...] @@ -448,9 +457,9 @@ ========================================= Finally, Alice gets back from lunch and sees that the carrier pigeon -with her second review has arrived (or maybe she just has it in her -email inbox). Alice's amended changeset has passed review, so she -pushes her fix to ``public``:: +with her second review has arrived (or maybe it's in her email inbox). +Alice's reviewer approved her amended changeset, so she pushes it to +``public``:: $ hg push ../public [...] @@ -472,10 +481,10 @@ | @ 4:cbdfbd5a5db2 (alice) |/ -Since Alice and Bob are already using advanced technology in the form -of shared mutable history, we'll assume they are perfectly comfortable -with rebasing changesets. So Alice rebases her changeset on top of -Bob's and publishes the result:: +We'll assume Alice and Bob are perfectly comfortable with rebasing +changesets. (After all, they're already using mutable history in the +form of ``amend``.) So Alice rebases her changeset on top of Bob's and +publishes the result:: $ hg rebase -d 5 $ hg push ../public