Spot documentation

[Eli Zaretskii]

> Date: Sun, 28 Mar 2010 21:32:38 -0500
> From: "Matthew D. Fuller" <fullermd at over-yonder.net>
> 
> I've just put up on the wiki my progress to date on filling out some
> spot documentation.
> 
> <http://wiki.bazaar.canonical.com/MatthewFuller/SpotDocs>

Thanks, I like it.

Some comments:

 . You tend to over-use "it", making it hard for the reader to connect
   the dots.  In general, my advice is to avoid using "it" except in
   the very next sentence, and provided that there's only one subject
   described in the previous sentence to which "it" can refer.
   Otherwise, always use the explicit word or phrase.  You should
   definitely _not_ use "it" in the next paragraph!  When a paragraph
   starts like this:

      It also contains some metadata describing it.

   the reader will have to go back to the previous paragraph and
   re-read large parts of it, to understand that "it" here refers to
   "revision".  This style also makes almost impossible to skip
   paragraphs that talk about things the reader is already familiar
   with.

   As another example, observe:

      Ancestry
      --------
      Importantly, it also stores a reference to the Revision it's
      derived from.

   Here we have a bona-fide riddle: what does "it" refer to?  Does it
   refer to "revision", to "ancestry", or to something else?

 . 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 the "Branches" section, it would be good to mention the "tip"
   terminology as well, as it tends to be used quite a lot in Bazaar
   parlance.

> * 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.

One question that is left unanswered is whether using "bzr merge"
where push/pull will do is a Bad Idea, and what will happen with the
DAG if I do use it.

Another question is whether push/pull can be used for adding to
mainline revisions from a branch that was merged with mainline during
its development.  IOW, imagine I have a branch where I develop some
feature, and which I resync with mainline from time to time by "bzr
merge".  It sounds like the changes from mainline will thus be present
in the branch, as result of the merges, but none of the changes on the
branch will be present in mainline.  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?