evolve: comparison docs/sharing.rst

equal deleted inserted replaced

-:35d053d7bd87
+:a456f55b3a6b
 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 *target* repository so that it is non-publishing.
+reconfiguring the *remote* repository so that it is non-publishing.
 (Short version: set ``phases.publish`` to ``false``. Long version
 follows.)
 Setting up
 ==========
 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
 [phases]
 publish = false
 [extensions]
-evolve = /path/to/evolve-main/hgext3rd/evolve/
+evolve =
 Then edit the configuration for ``dev-repo``::
 $ hg -R dev-repo config --edit --local
 and add ::
 [extensions]
-evolve = /path/to/evolve-main/hgext3rd/evolve/
+evolve =
 Keep in mind that in real life, these repositories would probably be
 on separate computers, so you'd have to login to each one to configure
 each repository.
 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 As seen in figure 3, this transfers the new changeset *and* the
 obsolescence marker for revision 1. However, it does *not* transfer
 the temporary amend commit, because it is hidden. Push and pull
-transfer obsolesence markers between repositories, but they do not
+transfer obsolescence markers between repositories, but they do not
 transfer hidden changesets.
 [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete]
 Because of this deliberately incomplete synchronization, revision
 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
 $ hg -R alice config --edit --local
 and add ::
 [extensions]
-evolve = /path/to/evolve-main/hgext3rd/evolve/
+evolve =
 Then edit Bob's repository configuration::
 $ hg -R bob config --edit --local
 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:
 and add ::
 [extensions]
 rebase =
-evolve = /path/to/evolve-main/hgext3rd/evolve/
+evolve =
 [phases]
 publish = false
 Then edit Bob's repository configuration::
 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::
 $ hg evolve --all
-Figure 8 illustrate's Bob's repository after evolving away the bumped
+Figure 8 illustrates Bob's repository after evolving away the bumped
 changeset. Ignoring the obsolete changesets, Bob now has a nice,
 clean, simple history. His amendment of Alice's bug fix lives on, as
 changeset 5:227d—albeit with a software-generated commit message. (Bob
 should probably amend that changeset to improve the commit message.)
 But the important thing is that his repository no longer has any
 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

branch	mercurial-3.9
changeset 3004	a456f55b3a6b
parent 2932	0afd41ac31d2
child 4615	8406d9b06130