Review of Chapter 4: Branching and Merging
sussman at red-bean.com
Sat Feb 24 11:40:57 CST 2007
Thanks for the review! Responses below.
On 2/24/07, C. Michael Pilato <cmpilato at red-bean.com> wrote:
> "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.
Fixed. Changed to "And how here is the easier method.... :"
> "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.
Fixed, changed 'mirror' to 'portion'.
> 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."
Great suggestion, thanks! I used almost your exact wording.
> 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.
I agree, I got rid of the numbering. Also, I reversed the order of
the ideas. The first idea expresses what you say: "subversion has
only copies, not branches", and the second idea says "thus branches
live in directory-space, not in a extra dimension". I've rewritten
the whole thing into a much clearer paragraph.
> "Subversion does not support cross-repository copying" -- would
> "inter-repository" be more clear? I've got no strong opinion on this.
Instead of bikeshedding, I just changed the sentence to "Subversion
does not support copying between different repositories."
> "Copying Changes Between Branches" has quite a few examples of doing
> single-revision merges, but nary a mention of the new -c option.
Good catch! I fixed a whole bunch of these, converting -r into -c
where I could.
Question: in the 'undoing changes' section, which shows a reverse
merge like -r88:87, should I use the slightly obtuse 'reverse change'
notation of '-c -88' ? I fear that may cause confusion, and might be
better left for the command reference section.
> "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.)
Don't we predict the obliteration feature in chapter 5, though? Or
the merge-tracking feature in chapter 4?
Hmmm... though... obliteration and merge-tracking have a 98% chance of
being implemented, whereas this patch format is more wishy-washy and
less likely. I've removed the mention of it.
> "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.
Ok, I inserted this a bit earlier into the paragraph.
> "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.
Sure, I changed it to 'user' error instead. (But c'mon, you seriously
think a windows user is going to think we suddenly started talking
about hardware drivers in the middle of this chapter? :-) People
have better context-processors than you give them credit for.)
> "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.
OK, intsead of saying "because move and copy commands aren't so
robust", I've changed it to "the update command isn't so robust",
since that's the primary cause of the problem here.
> "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.)
OK, I've removed the phrase 'true renames', so as to not make users
wonder what that phrase means (and begin speculating wildly). I *do*
still have to say that 'mv == cp + rm', however. We give this
detailed explanation of how 'svn up' fails to transmit copy
information, but unless the user understands that moves involve copies
(and deletes!), then they're going to be left wondering why move
operations are vulnerable to the problem. The whole pseudo-data-loss
example revolves around the explanation that a move is really a copy
(I agree, we shouldn't be apologizing for the way svn moves work, so
I've removed that aspect. But we don't need to actively hide that
information out of shame, either!)
> "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.
It's not heresay, it's been discussed to death a thousand times. It's
in the issue tracker. People have worked on the problem many times
and backed away in frustration (including you!). It's such a hot
issue, we have users endlessly writing nagging comments in the issue
tracker to finish it... they're even volunteering to help. I've never
seen a single svn developer object to the idea, in fact... *everyone*
wants it, and hasn't been able to make it happen yet. It's so highly
regarded, in fact, that it's on everyone's 'to do' list for svn 2.0
(assuming we can't make it happen in 1.x).
That's not 'heresay', that's the "community actively struggling for
years on the problem." It's exactly what the text says: that the
community 'has plans' to make it happen.
> "Switching a Working Copy" -- There's a TODO note somewhere about
> changing this title. It's nonsense to the uninitiated reader.
Ah yes, thanks, I remember this TODO. I've changed the title to
"Traversing Branches". if you have better suggestions, I'm all ears.
> "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.
Great suggestion, done.
> "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. :-)
Ok, I added a couple sentences.
> 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).
Sometimes the 'long story' format works best, particularly when the
concepts themselves build on each other. All of our chapters sort of
skim the line between 'story' and 'reference', and this one tends to
be more on the story-end of the scale. If someone has no experience
with branches and tags, they can't just figure them out by opening
chapter 4 to a random section and skimming... I can't imagine this
chapter ever as a reference. This is one of those topics that really
requires focused long-form reading and absorbtion of concepts.
More information about the svnbook-dev