New evolve docs, take 2: 1/3: index.rst

Angel Ezquerra angel.ezquerra at gmail.com
Fri May 30 17:32:37 UTC 2014


El 30/05/2014 18:45, "Greg Ward" <greg at gerg.ca> escribió:
>
> Hi Pierre-Yves --
>
> after mulling over your comments, I've ended up pretty much rewriting
> index.rst. I think it's much better, and I *think* it takes all of
> your criticims into account. Please see for yourself...

Greg, very nice write up. I have a couple of small comments below.

> '''
> .. 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
>
> With core Mercurial, changesets are permanent and immutable. You can
> commit new changesets to modify your source code, but you cannot
> modify or remove old changesets—they are carved in stone for all
> eternity.
>
> For years, Mercurial has included various extensions that allow
> history modification: ``rebase``, ``mq``, ``histedit``, and so forth.
> These are useful and popular extensions, and in fact history
> modification is one of the big reasons DVCSes (distributed version
> control systems) like Mercurial took off.
>
> But there's a catch: until now, Mercurial's various mechanisms for
> modifying history have been *unsafe*, in that changesets were
> destroyed (“stripped”) rather than simply made invisible.
>
> ``evolve`` makes things better in a couple of ways:
>
>   * It changes the behaviour of most existing history modification
>     extensions (``rebase``, ``histedit``, etc.) so they use a safer
>     mechanism (*changeset obsolescence*, covered below) rather than
>     the older, less safe *strip* operation.
>
>   * It provides a new way of modifying history that is roughly
>     equivalent to ``mq`` (but much nicer and safer).
>
> It helps to understand that ``evolve`` builds on infrastructure
> already in core Mercurial:
>
>   * *Phases* (starting in Mercurial 2.1) allow you to distinguish
>     mutable and immutable changesets. We'll cover phases early in the
>     user guide, since understanding phases is essential to
>     understanding ``evolve``.
>
>   * *Changeset obsolescence* (starting in Mercurial 2.3) is how
>     Mercurial knows how history has been modified, specifically when
>     one changeset replaces another. In the obsolescence model, a
>     changeset is neither removed nor modified, but is instead marked
>     *obsolete* and typically replaced by a *successor*. Obsolete
>     changesets usually become *hidden* as well. Obsolescence is an
>     invisible feature until you start using ``evolve``, so we'll cover
>     it in the user guide too.
>
> 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." (While this is possible using existing
>     features of core Mercurial, ``evolve`` makes it safer.)

I'd say that evolve makes it safE :-)

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

I think "back up" is confusing in this context. I guess you mean going back
to the broken revision, don't you? Or do you mean creating a backup of you
working directory changes?

The rest seems fine to me.

Cheers,

Angel

>   * Remove unwanted changes: "I hacked in some debug output two
>     commits back; everything is working now, so I'll just prune that
>     unwanted changeset and evolve history before pushing."
>
>   * Share mutable history with yourself: say you do most of your
>     programming work locally, but need to test on a big test server
>     somewhere before you know everything is good. You can use
>     ``evolve`` to share mutable history between two computers, pushing
>     finely polished changesets to a public repository only after
>     testing on the test server.
>
>   * Share mutable history for code review: you don't want to publish
>     unreviewed changesets, but you can't block every commit waiting
>     for code review. The solution is to share mutable history with
>     your reviewer, amending each changeset until it passes review.
>
> Next steps:
>   * For a practical guide to using ``evolve`` in a single repository,
>     see the `user guide`_.
>   * For mode advanced tricks, see `sharing mutable history`_.
>   * To learn about the concepts underlying ``evolve``, see `concepts`_.
>   * 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
> '''
>
> Greg
> _______________________________________________
> Evolve-testers mailing list
> Evolve-testers at selenic.com
> http://selenic.com/mailman/listinfo/evolve-testers
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurial-scm.org/pipermail/mercurial-evolve-testers/attachments/20140530/622c1e67/attachment-0002.html>


More information about the Evolve-testers mailing list