New evolve docs, take 2: 1/3: index.rst
Pierre-Yves David
pierre-yves.david at ens-lyon.org
Fri May 30 05:44:24 UTC 2014
On 05/28/2014 11:35 AM, Greg Ward wrote:
> .. 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:
"all of that" or "some of that" ?
Also: note sure what you are trying to achieve with this distinction
between "Mutable history" and "evolve". If you want to distinct the
concept from the experimental extension, you can use "Changeset
Evolution instead"
>
> * changesets that you modify or remove are not lost; they are simply
> marked *obsolete* and eventually become *hidden*
Wait, you just said that history is immutable and that changeset are
permanent. And now you say that evolve changes the way modification happens
> * you cannot mutate changesets that have been published (this is
> actually a feature of core Mercurial that was added to support
> changeset evolution)
>
> * you can safely share mutable history with your colleagues
Ok, I'm no half confused by this introduction. What about something that
unfold like this:
1. history was immutable
2. DVCS lets you rewrite it. that is a nice feature that people want.
But there is issues.
3. Changeset evolution brings improvement:
- Explicit distinction between mutable and immutable (phases)
- Easy access to older content and history of the rewriting that as been
done.
- Easy collaboration by propagation of rewriting and automatic
resolution of issue that arise.
- Nice UI
4. A list of more precise thing as the one right below.
> 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.)
You probably needs to defines safer. Something in the previous section
would do it.
>
> * 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: say you do most of your programming work
> locally, but need to test on a big development 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 dev server.
side note: a link to an appropriate section in the help for each of this
point would be nice.
> 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).
Phases are Mercurial-2.1. Obsolete markers are the feature that made is
in code for Mercurial-2.3.
> 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.
You should probably says that evolve change the behavior of
-core-mercurial-. Using rebase as an example. Hinting that core is
already fully aware of all that but disabled would be a nice bonus
> Next steps:
> * For a practical guide to using ``evolve``, see the `user guide`_.
> * For rocket-science 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
That part sound pretty solid.
--
Pierre-Yves David
More information about the Evolve-testers
mailing list