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