Review of Chapter 4: Branching and Merging

[C. Michael Pilato]

"And now the easier method of creating a branch, which we should have
told you about in the first place: svn copy is able to operate directly
on two URLs."  -- This is not a grammatically sound sentence.  The left
side of the colon must be able to stand alone.

"It's an easier procedure, because it doesn't require you to check out a
large mirror of the repository." -- The term "mirror" has come to have a
different meaning with the introduction of svnsync.  But besides that,
while the checkout described is certainly a nasty one, it doesn't really
contain all the data in the whole repository.  Just tweak the phrasing
here to more precise.

In the "Cheap Copies" sidebar: "From there, the copy is said to be
“lazy”."  No, it isn't.  The original copy is very *not* lazy.  Suggest
avoid the complexity of the "lazy" definition, and just finishing off
that paragraph with something like:  "And as further changes are made to
the files and directories beneath that copied directory, Subversion
continues to employ this hard-link concept.  It only duplicates data
when it is necessary to do so for the purposes of disambiguating
different versions of things."

In "The Key Concepts Behind Branches", I think the ordering of the two
points is backwards.  Subversion doesn't have "branches" and "tags" --
it has copies.  And because copies operate in directory-space, the
conceptual image of a branch in Subversion doesn't invoke the extra
dimension.  Also, here is a place where I don't think an actual numbered
list is meaningful.  Numbered lists imply ordering and sequence -- they
aren't just convenient ways to keep a running count of how many thoughts
you're expressing.

"Subversion does not support cross-repository copying" -- would
"inter-repository" be more clear?  I've got no strong opinion on this.

"Copying Changes Between Branches" has quite a few examples of doing
single-revision merges, but nary a mention of the new -c option.

"In the future, the Subversion project plans to use (or invent) an
expanded patch format that describes changes in tree structure and
properties."  Objection, Your Honor -- heresay.  (Seriously, I really
don't think we should make predictions about what Subversion features
will and won't appear later.  Doing so is of minimal value to our readers.)

"Why Not Use Patches Instead?" sorta implies at the very end that using
'svn merge' is better because it handles property merges, but I think it
useful to explicitly note that this is information that 'patch' cannot
correctly carry.

"they're the classic sign of driver error."  I suspect the tendency of
Windows users is to interpret "driver error" as something entirely
different than what you mean.  Let's avoid this jargon.

"Alas, this scenario doesn't work so well right now, and is considered
one of Subversion's current weak spots. The problem is that Subversion's
move and copy commands aren't as robust as they should be."  Having
spent no small amount of time considering the problem of atomic renames,
I'm pretty confident that the lack of them is absolutely not the cause
of the problems you are describing here.  The problems is, as you later
state, the fact that the repository doesn't transmit enough information
back to the client for the client to do the optimal/correct thing.

"A lesser-known fact about Subversion is that it lacks “true renames” —
the svn move command is nothing more than an aggregation of svn copy and
svn delete."  While it is true that we don't have "true renames",
dropping that piece of terminology like that without a suitable
explanation of what you mean is somewhat pointless.  (And besides, I
don't think it's a lesser-known fact to folks that use the operation.
Further, if it *is* a lesser-known fact, it's because the Subversion
developer community obscures it when we brag that we have support for
moves when, in fact, we have merely a close approximation of such support.)

"Moral of the story: until Subversion improves, be very careful about
merging copies and renames from one branch to another."  Another
grammatically challenged non-sentence here.  Left side.  Colon.
Standalone.  Yadda yadda.

"The Subversion project has plans, however, to someday implement a
command that would accomplish the task of permanently deleting
information."  Objection, Your Honor -- heresay.

"Switching a Working Copy" -- There's a TODO note somewhere about
changing this title.  It's nonsense to the uninitiated reader.

"This example assumes that a /calc/tags directory already exists. (If it
doesn't, see <xref-to-svn-mkdir>)"  I know what you mean, but simply
looking up 'svn mkdir' in the reference will not create a directory in
your repository.  We shouldn't be using cross-references as cheap
hyperlinks, despite the fact that their HTML and PDF rendering allows
such a usage.  Remember, that the xref evaluates to the text "svn mkdir"
instead of something as generic as "here" is at the discretion of the
rendering tools.  Suggest:  "This example assumes that a /calc/tags
directory already exists. (If it doesn't, you can always create it using
'svn mkdir'.)"  I don't think the cross-reference is necessary here.

"Remember the Subversion mantra: branches and tags are cheap. So use
them liberally!"  +1 on encouraging folks to not fear branches and tags.
 But I think this final sentiment should reiterate that liberal use of
branches and tags should be accompanied by good merge practices.
Proliferation of branches where poor merge recordkeeping exists is a
recipe for great suffering.  :-)

Overall, I think it's a good chapter.  The sections unfortunately tend
to depend on their predecessors in the development of a long-lived
example scenario, but that might be okay for this chapter (which reads
like a long story instead of a like just a bunch of related snippets).

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