Review of Chapter 2: Basic Usage
Brian W. Fitzpatrick
fitz at red-bean.com
Sat Feb 24 23:17:08 CST 2007
> Running with the previously made agreement that, to the degree possible,
> we won't try to mention concepts earlier in the book than their proper
> introduction, there are some issues that arise fairly early in the chapter.
>
> * The section on getting data into the repository is introducing 'svn
> import' and 'svn add'. No problem with 'svn import', but the part
> about 'svn add' requires a working copy (though we've not
> mentioned how to get one yet) and casually mentions 'svn commit'
> (without further explanation -- though, at least in this case
> 'commit' was mentioned in Chapter 1).
>
> Perhaps we should simply explain 'svn import' here, and note that
> later in the chapter we'll talk about other ways to add files to
> version control (since we do cover 'add' again later as part of
> the "making changes" section).
Done. I dropped the svn add here and pointed to later in the chapter.
> * Shortly after introducing checkouts, we smack users with "Disabling
> Password Caching", which is a pretty hefty topic. Seems that
> Chapter 1 (where fundamentals are discussed) should mention the
> fundamental fact that Subversion can operate over a network and
> supports authentication. In fact, Chapter 1 does talk about
> a client/server model, but is using the terms "Repository" and
> "Client". It's really kinda wierd that way.
I'll leave that to Ben then. :)
> I don't like that we explain each and every status code in this chapter.
> That's reference material. Choosing some common examples to
> demonstrate is fine, but the exhaustive list need live only in the
> reference. The current state is a hugely imbalanced attention to the
> finer details of 'svn status' compared to the level of exposition
> provided for the other subcommands. And it also means we have several
> links to later chapters because some of the status codes have more
> advanced meanings.
That makes a lot of sence--I pulled 80% of it and added a pointer to
the reference chapter. I'll make sure that the reference chapter
covers everything that we covered here.
> I've similar complaints about the exhaustive list of 'svn update' output
> codes.
Did the same here.
> The variable list section containing "File changes" and "Tree changes"
> is unnecessary. I'd just merge the info there into the two paragraphs
> which follow it.
Done.
> I think we should promote 'svn mkdir' as a commonly used operation. It
> certainly is for me, but more importantly, there are multiple references
> to it in the "Basic Work Cycle" section that might make more sense if it
> was quickly explained alongside add, delete, copy and move.
Agreed--done. Heck, there's plenty of room now that I pulled out all
that svn status and svn update cruft! :-)
> "Earlier in this chapter, we said that you have to commit any changes
> that you make in order for the repository to reflect these changes.
> That's not entirely true--there are some use cases that immediately
> commit tree changes to the repository." This seems contradictory --
> "earlier we said you have to commit, but we lied, because sometimes you
> can commit another way". I know what is meant here; I don't think our
> readers will.
Done. It was actually a total lie--there wasn't anywhere in the
chapter where we said that. Doh.
> "Look Ma! No Network!" begins, "All three of these commands (svn
> status, svn diff, and svn revert) can be used without any network
> access..." Sidebars should be self-sufficient, able to be read
> independent of the surrounding chapter context. But "these commands"
> has a dependency on that context. Remember that in print, sidebars may
> get moved around so that they fit nicely on the printed page -- the
> context in our HTML and PDF renderings isn't guaranteed to be the same
> context in the printed book.
Tweaked.
> The footnote that begins "Subversion uses its internal diff engine,
> which produces unified diff format, by default." is a little out of
> date. In Subversion 1.4.0, you can get whitespace-ignoring diffs
> without using an external diff tool. Maybe pick a different peculiarity
> of GNU diff to highlight?
Fixed to ignore case differences instead.
> "Undoing Working Changes" begins, "Now suppose you see the above diff
> output..." First, we can't say "above" -- that implies page
> positioning. But more importantly, it binds the section to the previous
> one, and this is something we try to avoid. This section doesn't need
> to refer to a diff in a previous section, because "setting up" the
> example is a really trivial task. "Suppose while viewing the output of
> 'svn diff' you determine that all the changes you made to a particular
> file are mistakes. Maybe you shouldn't have changed the file at all, or
> perhaps it would be easier to make different changes starting from scratch."
Perfect. Fixed.
> "You're probably wondering why we don't just use svn update --revision
> to update the file to the older revision.... it's sometimes just easier
> to look at an older version of a file in its entirety than to look only
> at the differences between it and another revision." These two
> sentences don't really make sense. 'svn update' isn't about viewing
> diffs, and *would* provide a way to see the old version of the file in
> its entirety.
Ah. I was unclear. The point I was trying to make is that sometimes
you just need a fulltext copy of an older revision while keeping your
current revision around. Anyway, they were prolix, so I pulled those 2
mini-paragraphs.
> I'm not completely thrilled with the relationship of this chapter to the
> other ones. That's not anybody's fault, really -- it's extremely
> difficult to present so many interrelated concepts in building-blocks
> order. But I'll start a different thread around that subject.
Okey doke. Changes incoming momentarily. Thanks again for the
awesome review--the chapter is feeling really tight now.
-Fitz
More information about the svnbook-dev
mailing list