# HG changeset patch # User Ryan McElroy # Date 1504107152 -7200 # Node ID 0afd41ac31d23f57c117d820710f33a84b4e822e # Parent 83d2c9637e896ec342dbcad09498182ab4ac2c99 sharing: edit pass diff -r 83d2c9637e89 -r 0afd41ac31d2 docs/sharing.rst --- 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