New user guide for evolve

[Angel Ezquerra]

On Sun, Apr 27, 2014 at 1:28 AM, Greg Ward <greg at gerg.ca> wrote:
> 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.

This is nice. I only have a couple of comments (see below).


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

I think it should say: "to support changeset evolution" or "to support
mutable/mutating history" or "to support evolve".


>   * 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"

I don't think this example highlights any new feature introduced by
evolve. Can't you already do this without evolve?
Maybe you should say that this keeps the old version around, or that
you can fix a _pushed_ revision as long as the remote repo is non
publishing.

That is all!

Cheers,

Angel