[SvnBook] #98: ch01: major reorganization
SvnBook
noreply at red-bean.com
Mon Mar 31 20:58:25 CDT 2008
#98: ch01: major reorganization
-------------------------+--------------------------------------------------
Reporter: cmpilato | Owner: nobody
Type: enhancement | Status: new
Priority: normal | Milestone:
Component: content | Version:
Keywords: |
-------------------------+--------------------------------------------------
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!)
* 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.
--
Ticket URL: <http://svnbook.red-bean.com/trac/ticket/98>
SvnBook <http://svnbook.red-bean.com/>
More information about the svnbook-dev
mailing list