--- a/docs/sharing.rst Wed Aug 30 17:32:32 2017 +0200
+++ b/docs/sharing.rst Wed Aug 30 17:32:32 2017 +0200
@@ -45,8 +45,8 @@
your test server before anything is carved in stone.
A less common scenario is multiple developers sharing mutable history,
-typically for code review. We'll cover this scenario later. But first,
-single-user sharing.
+typically for code review. We'll cover this scenario later. First, we
+will cover single-user sharing.
Sharing with a single developer
-------------------------------
@@ -55,8 +55,8 @@
==========================================
The key to shared mutable history is to keep your changesets in
-*draft* phase as you pass them around. Recall that by default, ``hg
-push`` promotes changesets from *draft* to *public*, and public
+*draft* phase as you pass them around. Recall that by default,
+``hg push`` promotes changesets from *draft* to *public*, and public
changesets are immutable. You can change this behaviour by
reconfiguring the *remote* repository so that it is non-publishing.
(Short version: set ``phases.publish`` to ``false``. Long version
@@ -90,7 +90,7 @@
The key to shared mutable history is to make the target repository, in
this case ``test-repo``, non-publishing. And, of course, we have to
-enable ``evolve`` in both ``test-repo`` and ``dev-repo``.
+enable the ``evolve`` extension in both ``test-repo`` and ``dev-repo``.
First, edit the configuration for ``test-repo``::
@@ -251,7 +251,7 @@
.. _`concept guide`: concepts.html
So the picture in ``public`` is much simpler than in either
-``dev-repo`` or ``test-repo``. Neither our missteps nor our amendments
+``dev-repo`` or ``test-repo``. Neither of our missteps nor our amendments
are publicly visible, just the final, beautifully polished changeset:
[figure SG05: public repo with rev 0:0dc9, 1:de61, both public]
@@ -508,13 +508,13 @@
but every competent chef keeps several around. Ever try to chop onions
with a spoon?)
-In the user guide, we saw examples of *unstable* changesets, which are
+In the user guide, we saw examples of *unstbale* changesets, which are
the most common type of troubled changeset. (Recall that a
-non-obsolete changeset with obsolete ancestors is unstable.)
+non-obsolete changeset with obsolete ancestors is an orphan.)
-Two other types of trouble can happen: *divergent* and *bumped*
-changesets. Both are more likely with shared mutable history,
-especially mutable history shared by multiple developers.
+Two other types of troubles can happen: *divergent* and
+*bumped* changesets. Both are more likely with shared mutable
+history, especially mutable history shared by multiple developers.
Setting up
==========
@@ -560,8 +560,8 @@
===============================
When an obsolete changeset has two successors, those successors are
-*divergent*. One way to get into such a situation is by failing to
-communicate with your teammates. Let's see how that might happen.
+*divergent*. One way to get into such a situation is by failing
+to communicate with your teammates. Let's see how that might happen.
First, we'll have Bob commit a bug fix that could still be improved::
@@ -621,22 +621,18 @@
``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs
when evolving divergent changesets using ``internal:local``.)
+# XXX this link does not work
.. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
** STOP HERE: WORK IN PROGRESS **
-Bumped changesets: only one gets on the plane
-=============================================
+Phase-divergence: when a rewritten changeset is made public
+===========================================================
-If two people show up at the airport with tickets for the same seat on
-the same plane, only one of them gets on the plane. The would-be
-traveller left behind in the airport terminal is said to have been
-*bumped*.
-
-Similarly, if Alice and Bob are collaborating on some mutable
+If Alice and Bob are collaborating on some mutable
changesets, it's possible to get into a situation where an otherwise
worthwhile changeset cannot be pushed to the public repository; it is
-bumped by an alternative changeset that happened to get there first.
+*phase-divergent* with another changeset that was made public first.
Let's demonstrate one way this could happen.
It starts with Alice committing a bug fix. Right now, we don't yet
@@ -676,21 +672,21 @@
This introduces a contradiction: in Bob's repository, changeset 2:e011
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
-Alice's repository (and ``public``), that changeset is public: it is
-immutable, carved in stone for all eternity. No changeset can be both
-obsolete and public, so Bob is in for a surprise the next time he
-pulls from ``public``::
+Alice's repository (and the ``public`` repository), that changeset is
+public: it is immutable, carved in stone for all eternity. No changeset
+can be both obsolete and public, so Bob is in for a surprise the next
+time he pulls from ``public``::
$ cd ../bob
$ hg pull -q -u
- 1 new bumped changesets
+ 1 new phase-divergent changesets
Figure 7 shows what just happened to Bob's repository: changeset
2:e011 is now public, so it can't be obsolete. When that changeset was
obsolete, it made perfect sense for it to have a successor, namely
Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical
-for a public changeset to have a successor, so 4:fe88 is in trouble:
-it has been *bumped*.
+for a public changeset to have a successor, so 4:fe88 is troubled:
+it has become *bumped*.
[figure SG07: 2:e011 now public not obsolete, 4:fe88 now bumped]
@@ -718,8 +714,8 @@
inattentive or careless user can do harm to himself or others.
Mercurial with ``evolve`` goes to great lengths to limit the harm you
can do by trying to handle all possible types of “troubled”
-changesets. But having a first-aid kit nearby does not excuse you from
-being careful with sharp knives.
+changesets. Nevertheless, having a first-aid kit nearby does not mean
+you should stop being careful with sharp knives.
Mutable history shared across multiple repositories by a single
developer is a natural extension of this model. Once you are used to