#4 Major reorganization of chapter 1

[Anonymous]

Originally created by: cmpilato
Originally owned by: cmpilato

[Was http://svnbook.red-bean.com/trac/ticket/98]

cmpilato:
{{{
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.

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!)
          o The repository (where your version controlled data is housed)
          o Revisions and versions
          o Version control models
    * How Subversion does version control
          o Subversion's high-level architecture (moved from the preface)
          o The Subversion repository (as a collection of tree snapshots,
addressable by a client using URLs, possibly over a network)
          o Revisions and versions (as global labels for those snapshots)
          o 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.
}}}

[Anonymous]

Originally posted by: cmpilato

I made these organizational changes in [r3798].

Labels: -Milestone-future Milestone-en-1.6
Status: Fixed