New evolve docs, take 2: 2/3: user-guide.rst

Pierre-Yves David pierre-yves.david at ens-lyon.org
Fri May 30 06:28:26 UTC 2014



On 05/28/2014 11:36 AM, Greg Ward wrote:
> .. Copyright © 2014 Greg Ward <greg at gerg.ca>
>
> ------------------
> Evolve: User Guide
> ------------------
>
> Add a changeset: ``commit``
> ---------------------------
>
> To create a new changeset, simply run ``hg commit`` as usual.
> ``evolve`` does not change the behaviour of ``commit`` at all.
>
> However, it's important to understand that new changesets are in the
> *draft* phase: they are mutable. This means that they can be modified
> by Mercurial's existing history-editing commands (``rebase``,
> ``histedit``, etc.), and also by ``evolve``.

maybe: and also by new command introduced by the evolve extension.

> Generally speaking,
> changesets remain in *draft* phase until they are pushed to another
> repository, at which point they enter *public* phase. ::

Maybe: we could emphasize the fact that a changeset turns public when it 
is -exchanged-. Because rewriting it will have consequence on other repo 
we do not control. Then say that for this happen automatically when you push

>    $ hg commit -m 'implement feature X'
>    $ hg phase -r .
>    1: draft
>
> (Strictly speaking, changesets only become public when they are pushed
> to a *publishing* repository. But you have to explicitly configure
> repositories to be *non-publishing*; all repositories are publishing
> by default. Non-publishing repositories are an advanced topic which
> we'll see when we get to `sharing mutable history`_.)

We could probably shorten that. Just pointing that automatic publishing 
on push can be changes, see XXX for details

>
> .. _`sharing mutable history`: sharing.html
>
> Modify (rewrite) a changeset: ``commit --amend``
> ------------------------------------------------

We can probably be more specific. What `commit --amend` does is
"adding more changes to a changeset" not sure about how to phrase that.

> Imagine you've just committed a new changeset, and then you discover a
> mistake. Maybe you forgot to run the tests and a failure slipped in.
> You want to modify history so that you push one perfect changeset,
> rather than one flawed changeset followed by an "oops" commit. (Or
> perhaps you made a typo in the commit message—this is really feature
> *Y*, not feature X. You can't fix that with a followup commit.)
>
> This is actually trivial with plain vanilla Mercurial since 2.2: fix
> your mistake and run ::
>
>    $ hg commit --amend -m 'implement feature Y'
>
> to create a new, amended changeset. The drawback of doing this with
> vanilla Mercurial is that your original, flawed, changeset is lost
> forever.

Not lost forever ! you have backup bundle. but its a pain to restore.

Pointing that the older version is easy accessible is a nice point to 
make. However I feel like this is coming too early.

I feel like you are mixing both basic user guide feature and more deep 
theoretical explanation. I wonder if we could built a better distinction 
between those two things.

Maybe shuffling the plan like that would work

A. Basic command on a head:
   1. basic amend usage on a head (skip the marker explanation)
   2. basic prune usage on a head
   3. basic uncommit usage on a head
   4. basic fold usage on a head

B. Mid-stack edit:

   - unstable + evolve: if you edit something with children, you have to 
take case of then

C. Wait what happened, this was magic and confusing
   - The old changeset is still around until then
   - We know the old changeset is obsolete because of marker
   - Marker contains also point to the new version

D. And this has happened all along?

   - Old changeset disapear when last unstable goes away
   - Show it is still accessible
   - Show all previous step actually did this too
   - (maybe points to revision number, but I'm not sure I want to see 
them mentioned at all)

E. Taking advantage of the obsgraph

   - how to see obsolete changeset
   - how to compare to them
   - how to restore previous version

F. More advance example.


(The above plan is proposal quickly drafted. not the Omega of all proposal)

I believe most of the existing content could be preserved and just move 
in other place.

Bonus point if you user guide is also a valid .t file


-- 
Pierre-Yves David



More information about the Evolve-testers mailing list