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