New evolve docs, take 2: 2/3: user-guide.rst
Greg Ward
greg at gerg.ca
Sat May 31 01:31:15 UTC 2014
On 29 May 2014, Pierre-Yves David said:
> >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.
Yeah, good point. As a wise man once said to me: "Tell 'em what you're
going to tell them, tell them, then tell them what you just told 'em."
(Good advice, Dad!)
Reworked version:
However, it's important to understand that new changesets are in the
*draft* phase by default: they are mutable. This means that they can
be modified by Mercurial's existing history-editing commands
(``rebase``, ``histedit``, etc.), and also by the ``evolve``
extension. Specifically, ``evolve`` adds a number of commands that can
be used to modify history: ``amend``, ``uncommit``, ``prune``,
``fold``, and ``evolve``.
> >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
I don't understand. I've just done a quick test to confirm my
assumptions, and they were correct: draft changesets in repo A only
become public when they are pushed to a publishing repo B. Pulling
from A to B doesn't affect A. Cloning A to B doesn't affect A. Only
pushing affects A. (I'm not sure if that is the *desired* behaviour,
but it's what I'm seeing.)
> > $ 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
Yeah, we could. I wanted to introduce the idea of "publishing" early,
but it turns out not to come up again in the user guide. I still like
the existing text, but if you feel strongly about trimming it, I'll do
it.
> >
> >.. _`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.
Well... no. You know better than I do that all this talk of
"modification" is an oversimplification. IMHO "rewrite" is an
excellent one-word description of what's really going on. So is
"replace", which has the advantage of an obvious noun form:
"replacement".
> > $ 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.
Yep. How about "... is stripped (removed from the repository)"? Or
just "... is removed from the repository"?
>
> 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.
Hmmmmmmm. I like it better when people complain about punctuation or
terminology. Wholesale rearrangement is a PITA! But I have a horrible
feeling, deep in the pit of my stomach, that you might be right. Damn.
> 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
Yeah, good way to start out. No surprises, no conflicts, no trouble.
Everything works smoothly.
> 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
Hmmmm. I think these are in the wrong order. Unstable changesets are
easy to understand when you see the obsolete changesets that they
descend from. That argues for explaining obsolescence (Figure 2)
*before* a mid-stack amend.
> 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)
Yeah, all four use cases in "A. Basic command on a head" need to be
illustrated with a diagram. O joy, O fun, O how I hate drawing
diagrams... almost as much as I hate technical docs without diagrams.
;-)
IMHO the way to do this is an "Understanding changeset obsolescence"
interlude that comes after the four basic use cases, but before
"Mid-stack amend".
> E. Taking advantage of the obsgraph
>
> - how to see obsolete changeset
Just to make sure I'm not missing an easier way, this is "hg --hidden
log -vp -r $OBSREV" right?
> - how to compare to them
And this is "hg --hidden diff -r $OBSREV:$REV"?
> - how to restore previous version
hg touch, right? I've actually never used it! Does it need --hidden?
> Bonus point if you user guide is also a valid .t file
Not yet. So far I'm maintaining docs/user-guide.rst and
tests/test-userguide.t because I'm not sure of the best way to unify
them (and similar for the sharing guide). I want to concentrate on the
best possible documentation before worrying about implementation
details.
Greg
More information about the Evolve-testers
mailing list