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

[C. Michael Pilato]

Ben, I think this is written at the *perfect* level of detail.  Well done. 
Some minor review comments inline.

sussman wrote:
> @@ -1975,6 +1975,85 @@
>  
>      </sect2>
>  
> +    <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
> +    <sect2 id="svn.branchmerge.advanced.finalword">
> +      <title>The Final Word on Merge Tracking</title>
> +
> +      <para>The bottom line is that Subversion's merge-tracking
> +        feature has an extremely complex internal implementation, and
> +        the <literal>svn:mergeinfo</literal> property is the only
> +        window the user has into the machinery.  As of this writing
> +        (Subversion 1.5) there are numbers of edge cases and possible
> +        unexpected behaviors that may pop up.</para>

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.

> +      <para>For example, sometimes mergeinfo will be generated when
> +        running a simple <command>svn copy</command> or <command>svn
> +        move</command> command.  Sometimes mergeinfo will appear on
> +        files that you didn't expect to be touched by an operation.
> +        Sometimes mergeinfo won't be generated at all, when you expect
> +        it to.  Furthermore, the management of mergeinfo metadata has
> +        a whole set of taxonomies and behaviors around it, such
> +        as <quote>explicit</quote> versus <quote>implicit</quote>
> +        mergeinfo, <quote>operative</quote>
> +        versus <quote>inoperative</quote> revisions, specific
> +        mechanisms of mergeinfo <quote>elision</quote>, and
> +        even <quote>inheritance</quote> from parent to child
> +        directories.</para>
> +
> +      <para>We've chosen not to cover these detailed topics in this
> +        book for a couple of reasons.  First, the level of detail is
> +        absolutely overwhelming for a typical user.  Second, as
> +        Subversion continues to improve, we feel that a typcial
> +        user <emphasis>shouldn't</emphasis> have to understand these
> +        concepts; they'll eventually fade into the background as pesky
> +        implementation details.  All that said, if you enjoy this sort
> +        of thing, you can get a fantastic overview in a paper posted
> +        at Collabnet's
> +        website: <ulink 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.

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

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

> +            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 3.


-- 
C. Michael Pilato <cmpilato at red-bean.com> | http://cmpilato.blogspot.com/

"The Christian ideal has not been tried and found wanting.  It has
  been found difficult; and left untried."  -- G. K. Chesterton