--- 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