New user guide for evolve

[Greg Ward]

Hi all --

I've been working on improving the documentation for evolve. At least
the text of the new user guide is ready for peer review. (I'm still
working on drawing the figures.)

For future reference, you can pull from bookmark 'rewrite-docs' in

  http://hg.gerg.ca/mutable-history/

to get my latest version. But for now, I'm just going to dump the .rst
files into this email so that everyone can have their say.

First, the intro (index.rst):

"""
.. Copyright 2014 Greg Ward <greg at gerg.ca>

==================================
Changeset Evolution with Mercurial
==================================

`evolve`_ is an experimental Mercurial extension for safe mutable history.

.. _`evolve`: http://mercurial.selenic.com/wiki/EvolveExtension

Normally with Mercurial (and other sane version control systems), a
changeset is permanent and immutable. You can commit new changesets to
modify the source code, but you cannot modify or remove old
changesets. They are carved in stone for all eternity.

Mutable history changes all that, and ``evolve`` is an implementation
of mutable history with a number of nice properties:

  * changesets that you modify or remove are not lost; they are simply
    marked *obsolete* and eventually become *hidden*

  * you cannot mutate changesets that have been published (this is
    actually a feature of core Mercurial that was added to support
    evolution)

  * you can safely share mutable history with your colleagues

Some of the things you can do with ``evolve`` are:

  * fix a mistake immediately: "oops! I just committed a changeset
    with a syntax error -- I'll fix that and amend the changeset so no
    one sees my mistake"

  * fix a mistake a little bit later: "oops! I broke the tests three
    commits back, but only noticed it now -- I'll just back up, fix my
    mistake, amend the bad changeset, and evolve history to update the
    affected changesets"

  * remove unwanted changes: "I hacked in some debug output two
    commits back; everything is working now, so I'll just prune that
    unwanted changeset before pushing"

  * share mutable history: Alice and Bob can setup a shared private
    repository where they work on implementing a new feature. Alice
    pushes changeset A, Bob pulls it, and commits changeset B based
    on A. But then Alice notices a mistake in A, so she amends it and
    pushes A'. Bob pulls A': ``evolve`` notices that A' replaces A,
    and tells Bob he needs to evolve changeset B to B' so it is based
    on A' rather than A.

Additionally, ``evolve`` makes existing history-editing operations
(like ``rebase``) safer. For starters, Mercurial's "phases" feature
prevents you from rebasing published changesets, which was a common
source of pain in Mercurial pre-2.3 (when phases were first added).
More interestingly, ``evolve`` modifies the behaviour of ``rebase`` so
that rebased changesets are marked *obsolete* rather than removed
entirely from the repository. Finally, ``evolve`` makes it possible
for Alice and Bob to share mutable changesets without losing their
minds.

Next steps:
  * For a practical guide to using ``evolve``, see the `user guide`_.
  * To learn about the concepts underlying ``evolve``, see `concepts`_.
  * For rocket-science tricks, see `sharing mutable history`_.
  * If you're coming from MQ, see the `MQ migration guide`_.

.. _`user guide`: user-guide.html
.. _`concepts`: concepts.html
.. _`sharing mutable history`: sharing.html
.. _`MQ migration guide`: from-mq.html
"""

I'll followup with the new user guide in a separate message, so you
can reply to each document separately. I'll send concepts.rst later.
And I haven't started on the other two (although I'm hoping I can
steal from the existing docs for them).

       Greg
-- 
Greg Ward                            http://www.gerg.ca
<greg at gerg.ca>                       @gergdotca