evolve: comparison docs/sharing.rst

equal deleted inserted replaced

-:83d2c9637e89
+:0afd41ac31d2
 passing yet—just ``hg amend`` when they are. And you can transfer
 those half-baked changesets between repositories to try things out on
 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,
+typically for code review. We'll cover this scenario later. First, we
-single-user sharing.
+will cover single-user sharing.
 Sharing with a single developer
 -------------------------------
 Publishing and non-publishing repositories
 ==========================================
 The key to shared mutable history is to keep your changesets in
-*draft* phase as you pass them around. Recall that by default, ``hg
+*draft* phase as you pass them around. Recall that by default,
-push`` promotes changesets from *draft* to *public*, and public
+``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
 follows.)
 we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
 there, and push to ``public``.
 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``::
 $ hg -R test-repo config --edit --local
 hidden changesets on push and pull.
 .. _`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]
 There is one important step left to do. Because we pushed from
 Mercurial with ``evolve`` is a powerful tool, and using powerful tools
 can have consequences. (You can cut yourself badly with a sharp knife,
 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*
+Two other types of troubles can happen: *divergent* and
-changesets. Both are more likely with shared mutable history,
+*bumped* changesets. Both are more likely with shared mutable
-especially mutable history shared by multiple developers.
+history, especially mutable history shared by multiple developers.
 Setting up
 ==========
 For these examples, we're going to use a slightly different workflow:
 Example 6: Divergent changesets
 ===============================
 When an obsolete changeset has two successors, those successors are
-*divergent*. One way to get into such a situation is by failing to
+*divergent*. One way to get into such a situation is by failing
-communicate with your teammates. Let's see how that might happen.
+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::
 $ cd bob
 $ echo 'pretty good fix' >> file1
 (``internal:other``) that will take Alice's changes over Bob's. (You
 might wonder why Bob wouldn't prefer his own changes by using
 ``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
+If Alice and Bob are collaborating on some mutable
-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
 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
 know if this bug fix is good enough to push to the public repository,
 but it's good enough for Alice to commit. ::
 [...]
 added 1 changesets with 1 changes to 1 files
 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
+Alice's repository (and the ``public`` repository), that changeset is
-immutable, carved in stone for all eternity. No changeset can be both
+public: it is immutable, carved in stone for all eternity. No changeset
-obsolete and public, so Bob is in for a surprise the next time he
+can be both obsolete and public, so Bob is in for a surprise the next
-pulls from ``public``::
+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:
+for a public changeset to have a successor, so 4:fe88 is troubled:
-it has been *bumped*.
+it has become *bumped*.
 [figure SG07: 2:e011 now public not obsolete, 4:fe88 now bumped]
 As usual when there's trouble in your repository, the solution is to
 evolve it::
 user can do wonderful things with it, much more wonderful than with a
 dull knife (never mind a rusty spoon). At the same time, an
 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
+changesets. Nevertheless, having a first-aid kit nearby does not mean
-being careful with sharp knives.
+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
 using a single sharp knife on its own, it's pretty straightforward to
 chop onions and mushrooms using the same knife, or to alternate

changeset 2932	0afd41ac31d2
parent 2865	b0b8cc3064b0
child 4615	8406d9b06130