Spot documentation

[Matthew D. Fuller]

On Mon, Mar 29, 2010 at 12:01:13PM +0300 I heard the voice of
Eli Zaretskii, and lo! it spake thus:
> 
> Some comments:

Thanks.  It may take me a while to act on it, but I do appreciate the
feedback!


>  . You tend to over-use "it",

Pfft.  It's not that bad.  In fact, it's generally agreed that it's
fine, and there's no reason to disturb it.  It's not like it inhibits
understanding it.   8-}


>  . In the "Hands Off!" section, you say a revision is immutable, but a
>    reader who is already familiar with Bazaar will immediately think
>    about "bzr uncommit".  It would be good to at least mention that
>    here, and explain how the existence of that command does not (or
>    does?) weaken the immutability of a revision.

In an earlier draft I actually had a couple paragraphs here talking
about situations like uncommit, and rebase/rewrite replacement of
parts of history.  I took it out as part of the pruning I did on that
whole article, because the article was just too stinkin' long.  It's
still too stinkin' long (as I mention on the top), even with glossing
over some special cases like this.  Definitely still needs work    :|



> > * A discussion of push, pull, and merge, how they differ, what they do
> >   to the revision graph, and when you'd use one or the other.
> 
> This section is good, but (like all other documents on this issue
> I've read) it considers only very simple use-cases.  In reality, the
> history DAG of each of the two branches will be much more complex
> than what you show.  And then the question how push, pull, and merge
> differ and when to use each one of them is not so straightforward,
> at least not for me.

This is tricky.  In a sense, of course, the more complex cases are
just extensions of the simple one shown.  And I'm intentionally
focusing on base concepts, rather than attempting an exhaustive
catalog of their implications.

But it may not be obvious how to extend the simple cases.  I'm at a
disadvantage here, with my existing understanding; I have a hard time
seeing at what point following the chain toward more complex breaks
down.  If you have some concrete cases where you find extrapolating
hits a wall, I'd like to hear them to give me some direction here.


This section is also tricky because you really need to inhale both it,
and the section talking about mainline/numbering, to really fully
understand either.  I made some earlier forays into doing both at
once, but they turned out more muddled then throwing up my hands and
having them separate-but-go-read-that-one-too.  Also a place needing
work   :|


> Another question is [...] Then, according to perhaps a naive reading
> of your text, push/pull are still appropriate when the time comes to
> land the feature from the branch to mainline?

This is another of those "pulling out implications" cases.  I think
this will be easiest to address in the planned article showing example
workflows?


Thanks for the feedback!


-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.