Spot documentation

[Matthew D. Fuller]

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>

These articles aren't meant to be a tutorial from scratch about how to
use bzr, nor to be a full reference manual.  Instead my intent is to
address some specific questions about how the pieces fit together in
bzr, what specific operations do in terms of the big picture, and why
you'd want to do one instead of the other.

They're built around my impressions of some common misunderstandings
and mental model shortcomings, with the intent that they can be used
as references to answer questions, and answer them fairly directly (to
be able to say "this specifically answers your question", rather than
a general handwaving sort of "if you grok everything in the docs,
you'll have your answer").

Current documents include:

* A description of what Revisions are and how they connect, and an
  explanation of the triumvirate of Repository, Branch, and Working
  Tree that bounds the Bazaar user interface model.

* A discussion of how revisions are numbered, including the Mainline
  concept and how dotted revnos come about.

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

The latter two cover some of the same territory and repeat each other
a bit, but I think they're best separate.  The former talks a lot
about the "why", and the latter about the "how".


Some future plans include:

* An attempt to run down the more common commands and describe what
  impact they have respectively on Revisions, Repositories, Branches,
  and Working Trees, to serve as a useful reference for understanding
  what effect running a command can have.

* More detailed investigation of different arrangements of our 3
  components.

* Possibly some imaginary case studies of different workflows and what
  sort of result you get in terms of the items above.

but don't look for them too soon, round tuits being in the supply they
are   :(


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