[svnbook commit] r3136 - trunk/src/en/book

Ben Collins-Sussman sussman at red-bean.com
Sun Jun 15 22:15:06 CDT 2008

On Sun, Jun 15, 2008 at 9:46 PM, C. Michael Pilato
<cmpilato at red-bean.com> wrote:
> Ben, I think this is written at the *perfect* level of detail.  Well done.
> Some minor review comments inline.

Cool, thanks!

> Do we really need to say "as of this writing"?  I mean, the book is already
> pegged to Subversion 1.5.  I think we've done away with similar phrases in
> the past.

I agree in general, except the text goes on to say that we expect the
bumpy road to vanish as merge-tracking matures.  We need to give the
readers some sense of when this expectation was set.  Imagine someone
reading our book in 2011, using Subversion 1.8, and they see that
merge-tracking is "set to improve in the future".  Is the book talking
about svn 1.5?  1.6? 1.7?  They have no sense when that prediction was

Maybe better text is "Because the feature is relatively new..."   Then
astute users can at least deduce that the text was written when
merge-tracking first came out.

>> url="http://www.collab.net/community/subversion/articles/merge-info.html">http://www.collab.net/community/subversion/articles/merge-info.html</ulink>.</para>
> I'm a teeny bit nervous about linking to CollabNet's website -- not sure
> they have a real incentive to persist information forever.  But I won't make
> a big fuss about it.

It's probably ok, though if we were really paranoid, maybe we'd link
to the notes/ directory in the source tree or something... ?

>> +      <itemizedlist>
>> +        <listitem>
>> +          <para>For short-term <quote>feature</quote> branches,
>> +            follow the simple procedure described throughout
>> +            <xref linkend="svn.branchmerge.basicmerging"/>.</para>
>> +        </listitem>
>> +        <listitem>
>> +          <para>For long-lived <quote>release</quote> branches (as
>> +            described in
>> +            <xref linkend="svn.branchmerge.commonpatterns"/>), only
>> +            perform merges on the root of the branch, not on +
>>  subdirectories.</para>
>> +        </listitem>
>> +        <listitem>
>> +          <para>Never merge into working copies with a mixture of
>> +            working revision numbers, or with
>> +            <quote>switched</quote> subdirectories (as described +
>>      in <xref linkend="svn.branchmerge.switchwc"/>).  A merge
>> +            target should be a working copy which represents
>> +            a <emphasis>single</emphasis> location in the repository
>> +            at a single point in time.</para>
>> +        </listitem>
> There are an *awful log* of <quote> tags in this new section.  All of the
> ones in this list seem superfluous to me.  If the reader is arriving at this
> section after reading your awesome chapter 4, they'll know these terms.

Hm, sorta.  This isn't at the end of the chapter, it's the middle of
the chapter.  It's at the end of the *merging* section, but there are
still sections following on 'svn switch', common branching patterns,
etc.  So the reader doesn't yet know what "switched" means, and if
they're really naive, they don't know what a release branch is either.
 That said, I removed the quotes on "feature" branch and "release"
branch... but I left them on "switched".

>> +        <listitem>
>> +          <para>Don't ever edit the <literal>svn:mergeinfo</literal>
>> +            property directly; use <command>svn
>> +            merge --record-only</command> to effect a desired change
>                                                 ^^^^^ affect

Nope, this is correct.  :-)  Google for this usage.  It's one of the
very rare (but legal) uses of 'effect' as a verb, rather than a noun.

>> +            to the metdata (as demonstrated in
>                       ^^^^^ metadata


>> +            <xref
>> linkend="svn.branchmerge.advanced.blockchanges"/>).</para>
>> +        </listitem>
>> +        <listitem>
>> +          <para>Always make sure you have complete read access to
>> +            all of your merge sources, and that your target working
>> +            copy is entirely at <option>--depth
>> +              infinity</option>.</para>
> "at depth infinity" isn't such a common idea.  Maybe say "that your target
> working copy has no sparse directories" and xref to that section of chapter

Ahh, great idea.

More information about the svnbook-dev mailing list