comparison docs/sharing.rst @ 1261:56cc2eb5995a stable

docs: add code review scenario to sharing guide

The idea is to demonstrate a simpler multiple-developer situation that
does not involve getting into trouble.

The final scenario illustrates Alice and Bob getting into trouble with
bumped and divergent changesets by amending each other's history. The
required tests and text are all written, but will need to be heavily
revised because of the inserted scenario.

1260:e8016d1011b5

------------------------------

.. contents::

Once you have mastered the art of mutable history in a single
repository (see the `user guide`_), you might want to move up to the
next level: *shared* mutable history. ``evolve`` lets you push and
pull draft changesets between repositories along with their
obsolescence markers. This opens up a number of interesting
possibilities.

.. _`user guide`: user-guide.html

The simplest scenario is a single developer working across two
computers. Say you're working on code that must be tested on a remote

than what came before.) The latter, avoiding version control entirely,
means that you're walking a tightrope without a safety net. One
accidental ``rsync`` in the wrong direction could destroy hours of
work.

Using Mercurial with ``evolve`` to share mutable history solves all of
these problems. As with single-repository ``evolve``, you can commit
whenever the code is demonstrably better, even if all the tests aren't
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.

follows.)

Setting up
==========

We'll work an example with three local repositories, although in the
real world they'd most likely be on three different computers. First,
the ``public`` repository is where tested, polished changesets live,
and it is where you synchronize changesets with the rest of your team.
::

  $ hg init public

We'll need two clones where work gets done::

  $ hg clone public test-repo
  updating to branch default
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone test-repo dev-repo

everything configured just the way you like it. ``test-repo`` is the
test server in a rack somewhere behind SSH. So for the most part,
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,
``test-repo`` in this case, non-publishing. And, of course, we have to enable ``evolve`` in both ``test-repo`` and ``dev-repo``.

First, edit the configuration for ``test-repo``::

  $ hg -R test-repo config --edit --local

obsolete in ``test-repo``, having been replaced by revision 3:60ff
(revision 2:2a03 is another one of those temporary amend commits that
we saw in the user guide)—but ``dev-repo`` knows nothing of these
recent developments.

  [figure SG02: rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft -- but dev-repo same as in SG01]

Let's resynchronize::

  $ cd ../dev-repo
  $ hg pull -u

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 obsolete. Push and pull
transfer obsolesence markers between repositories, but they do not
normally transfer obsolete changesets.

  [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete]

Because of this deliberately incomplete synchronization, revision
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We

  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files

Note that only one changeset—the final version, after two
amendments—was actually pushed. Again, Mercurial normally doesn't
transfer obsolete changesets on push and pull. (Specifically, it
doesn't transfer *hidden* changesets: roughly speaking, obsolete
changesets with no non-obsolete descendants. If you're curious, see
the `concept guide`_ for the precise definition of hidden.)

.. _`concept guide`: concepts.html

So the picture in ``public`` is much simpler than in either
``dev-repo`` or ``test-repo``. None of our missteps or amendments are

public. Let's avoid that situation for now by pulling from
``test-repo`` down to ``dev-repo``::

  $ cd ../dev-repo
  $ hg pull -u

Sharing with multiple developers
--------------------------------

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

non-obsolete changeset with obsolete ancestors is unstable.)

Two other types of trouble can crop up: *bumped* and *divergent*
changesets. Both are more likely with shared mutable history,
especially mutable history shared by multiple developers.

Setting up
==========

To demonstrate, let's start with the ``public`` repository as we left
it in the last example, with two immutable changesets (figure 5
above). Two developers, Alice and Bob, start working from this point::

  $ hg clone public alice
  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone public bob
  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``::

  $ cat >> alice/.hg/hgrc <<EOF
  [phases]
  publish = false
  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py
  EOF
  $ cp alice/.hg/hgrc bob/.hg/hgrc

Bumped changesets: only one gets on the plane
=============================================

If two people show up at the airport with tickets for the same seat on

1261:56cc2eb5995a

------------------------------

.. contents::

Once you have mastered the art of mutable history in a single
repository (see the `user guide`_), you can move up to the next level:
*shared* mutable history. ``evolve`` lets you push and pull draft
changesets between repositories along with their obsolescence markers.
This opens up a number of interesting possibilities.

.. _`user guide`: user-guide.html

The simplest scenario is a single developer working across two
computers. Say you're working on code that must be tested on a remote

than what came before.) The latter, avoiding version control entirely,
means that you're walking a tightrope without a safety net. One
accidental ``rsync`` in the wrong direction could destroy hours of
work.

Using Mercurial with ``evolve`` to share mutable history solves these
problems. As with single-repository ``evolve``, you can commit
whenever the code is demonstrably better, even if all the tests aren't
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.

follows.)

Setting up
==========

We'll work through an example with three local repositories, although
in the real world they'd most likely be on three different computers.
First, the ``public`` repository is where tested, polished changesets
live, and it is where you synchronize with the rest of your team. ::

  $ hg init public

We'll need two clones where work gets done, ``test-repo`` and
``dev-repo``::

  $ hg clone public test-repo
  updating to branch default
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone test-repo dev-repo

everything configured just the way you like it. ``test-repo`` is the
test server in a rack somewhere behind SSH. So for the most part,
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``.

First, edit the configuration for ``test-repo``::

  $ hg -R test-repo config --edit --local

obsolete in ``test-repo``, having been replaced by revision 3:60ff
(revision 2:2a03 is another one of those temporary amend commits that
we saw in the user guide)—but ``dev-repo`` knows nothing of these
recent developments.

  [figure SG02: test-repo has rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft; dev-repo same as in SG01]

Let's resynchronize::

  $ cd ../dev-repo
  $ hg pull -u
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  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 hidden changesets.

  [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete]

Because of this deliberately incomplete synchronization, revision
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We

  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files

Note that only one changeset—the final version, after two
amendments—was actually pushed. Again, Mercurial doesn't transfer
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``. None of our missteps or amendments are

public. Let's avoid that situation for now by pulling from
``test-repo`` down to ``dev-repo``::

  $ cd ../dev-repo
  $ hg pull -u
  [...]
  no changes found

Even though no *changesets* were pulled, Mercurial still pulled
obsolescence markers from ``test-repo``.

Sharing with multiple developers: code review
---------------------------------------------

Now that you know how to share your own mutable history across
multiple computers, you might be wondering if it makes sense to share
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.

Setting up
==========

To demonstrate, let's start with the ``public`` repository as we left
it in the last example, with two immutable changesets (figure 5
above). We'll clone a ``review`` repository from it, and then Alice
and Bob will both clone from ``review``. ::

  $ hg clone public review
  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone review alice
  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone review bob
  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 ::

  $ hg -R alice config --edit --local

and add ::

  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py

Then add the same text to Bob's repository configuration::

  $ hg -R bob config --edit --local

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

  $ hg bookmark bug15
  $ echo 'fix' > file2
  $ hg commit -A -u alice -m 'fix bug 15 (v1)'
  adding file2

Note the unorthodox "(v1)" in the commit message. We're just using
that to make this tutorial easier to follow; it's not something we'd
recommend in real life.

Of course Alice wouldn't commit unless her fix worked to her
satisfaction, so it must be time to solicit a code review. She does
this by pushing to the ``review`` repository::

  $ hg push -B bug15
  [...]
  added 1 changesets with 1 changes to 1 files
  exporting bookmark bug15

(The use of ``-B`` is important to ensure that we only push the
bookmarked head, and that the bookmark itself is pushed. See this
`guide to bookmarks`_, especially the `Sharing Bookmarks`_ section, if
you're not familiar with bookmarks.)

.. _`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::

  $ echo 'Fix.' > file2
  $ hg amend -m 'fix bug 15 (v2)'
  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  updating bookmark bug15

Figure 6 shows the state of the ``review`` repository at this point.

  [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
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. ::

  $ cd ../bob
  $ echo 'stuff' > file1
  $ hg bookmark featureX
  $ hg commit -u bob -m 'implement feature X (v1)'
  $ hg push -B featureX
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  exporting bookmark featureX

When Bob receives his code review, he improves his implementation a
bit, amends, and submits the resulting changeset for review::

  $ echo 'do stuff' > file1
  $ hg amend -m 'implement feature X (v2)'
  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  updating bookmark featureX

Unfortunately, that still doesn't pass muster. Bob's reviewer insists
on proper capitalization and punctuation. ::

  $ echo 'Do stuff.' > file1
  $ hg amend -m 'implement feature X (v3)'

On the bright side, the second review said, "Go ahead and publish once
you fix that." So Bob immediately publishes his third attempt::

  $ hg push ../public
  [...]
  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. ::

  $ hg push ../review
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  updating bookmark featureX

Figure 7 shows the result of Bob's work in both ``review`` and
``public``.

  [figure SG07: review includes alice's draft work on bug 15, as well as Bob's v1, v2, and v3 changes for feature X: v1 and v2 obsolete, v3 public. public contains only the final, public implementation of feature X]

Incidentally, it's important that Bob push to ``public`` *before*
``review``. If he pushed to ``review`` first, then revision 6:540b
would still be in *draft* phase in ``review``, but it would be
*public* in both Bob's local repository and the ``public`` repository.
That could lead to confusion at some point, which is easily avoided by
pushing first to ``public``.

Example 5: Alice integrates and publishes
=========================================

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

  $ hg push ../public
  [...]
  remote has heads on branch 'default' that are not known locally: 540ba8f317e6
  abort: push creates new remote head cbdfbd5a5db2!
  (pull and merge or see "hg help push" for details about pushing new heads)

Oops! Bob has won the race to push first to ``public``. So Alice needs
to integrate with Bob: let's pull his changeset(s) and see what the
branch heads are. ::

  $ hg pull ../public
  [...]
  added 1 changesets with 1 changes to 1 files (+1 heads)
  (run 'hg heads' to see heads, 'hg merge' to merge)
  $ hg log -G -q -r 'head()' --template '{rev}:{node|short}  ({author})\n'
  o  5:540ba8f317e6  (bob)
  |
  | @  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::

  $ hg rebase -d 5
  $ hg push ../public
  [...]
  added 1 changesets with 1 changes to 1 files
  $ hg push ../review
  [...]
  added 1 changesets with 0 changes to 0 files
  updating bookmark bug15

The result, in both ``review`` and ``public`` repositories, is shown
in figure 8.

  [figure SG08: review shows v1 and v2 of alice's fix, then v1, v2, v3 of bob's feature, finally alice's fix rebased onto bob's. public just shows the final public version of each changeset]


** STOP HERE: WORK IN PROGRESS **


Getting into trouble with shared mutable history
------------------------------------------------

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

non-obsolete changeset with obsolete ancestors is unstable.)

Two other types of trouble can crop up: *bumped* and *divergent*
changesets. Both are more likely with shared mutable history,
especially mutable history shared by multiple developers.

Bumped changesets: only one gets on the plane
=============================================

If two people show up at the airport with tickets for the same seat on