Thoughts on Chapter 1

[C. Michael Pilato]

As I noted last night, I'm dissatisfied with some section ordering and
the knowledge dependency graph in our book.  Currently on my hit list is
Chapter 1.

The chapter starts off with this weird section that conflates the idea
of a "server" with a "repository".  The very word "server" evokes
thoughts of networks, but of course networked operation is not a version
control basic.

Anyway, that is followed by the explanation of the various version
control models, which is the highlight of the chapter for me.

At this point, we're at the perfect place to talk about working copies.
  Now, neither of the version control models requires a physical working
copy.  a VC tool could rebuild and manage in memory the same stuff that
today lives in the .svn directories with each invocation.  But
Subversion has chosen to use a physical working copy, a cache of some of
the most commonly accessed bits of repository data.  It is in that
working "copy" where we do the "modify"cations that we later "merge"
into the repository.

But we don't introduce working copies.  We talk about URLs, because they
help us explain how to *get* a working copy.  *Then* we talk about
working copies.  But as part of talking about working copies, we throw
up a sidebar about URLs again.  It's in this sidebar that we finally get
around to mentioning that Subversion is a networked version control system.

(Oh, and the title "Subversion in Action" reads to me like an
advertisement for the circus.)

After that, we bring up revisions.  But why didn't mention revisions way
back we introduced the idea of a repository that remembers every change
ever written to it?

Finally, we talk about mixed-revision working copies, which I suppose is
fine.

I'm so confused when I read Chapter 1 that I'm not sure I can even make
clear suggestions on how to fix it.  But here's a straw man (I'm
shooting from the hip here, and aiming for clear layering of generic VC
concepts with Subversion specifics):

   * An introduction to version control (no Subversion info allowed!)
     * The repository (where your version controlled data is housed)
     * Revisions and versions
     * Version control models
   * How Subversion does version control
     * Subversion's high-level architecture (moved from the preface)
     * The Subversion repository (as a collection of tree snapshots,
       addressable by a client using URLs, possibly over a network)
     * Revisions and versions (as global labels for those snapshots)
     * How Subversion does copy-modify-merge
       * Working copies
         - copy: how to get them (checkout)
         - modify: how to change them (with an editor and svn commands
           to be described in detail in chapter 2)
         - merge: how to submit your changes (commit)
       * Mixed-revision working copies

As you can see, I'm aiming for a certain parallelism here.

Thoughts?

-- 
C. Michael Pilato <cmpilato at red-bean.com>

"The Christian ideal has not been tried and found wanting.  It has
 been found difficult; and left untried."  -- G. K. Chesterton