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