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

[Arfrever Frehtes Taifersar Arahesis]

2008-06-16 04:10:12 sussman napisał(a):
> Author: sussman
> Date: Sun Jun 15 21:10:11 2008
> New Revision: 3136
> 
> Log:
> * ch04-branching-and-merging.xml:  (issue 121) write new section mentioning the complexity of mergeinfo.
> 
> Modified:
>    trunk/src/en/book/ch04-branching-and-merging.xml
> 
> Modified: trunk/src/en/book/ch04-branching-and-merging.xml
> ==============================================================================
> --- trunk/src/en/book/ch04-branching-and-merging.xml	(original)
> +++ trunk/src/en/book/ch04-branching-and-merging.xml	Sun Jun 15 21:10:11 2008
> @@ -929,7 +929,7 @@
>            After performing a revert, be sure to clean up the working
>            copy and remove unversioned files and directories.  The
>            output of <command>svn status</command> should be as clean
> -          (read: empty) as possible!</para>
> +          as possible, ideally showing no output.</para>
>        </tip>
>  
>      </sect2>
> @@ -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>
> +
> +      <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

s/typcial/typical/

> +        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>
> +
> +      <para>For now, if you want to steer clear of bugs and odd
> +        behaviors in automatic merging, the Collabnet article
> +        recommends you stick to these simple best practices:</para>
> +
> +      <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>
> +        <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
> +            to the metdata (as demonstrated in
> +            <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>
> +        </listitem>
> +      </itemizedlist>
> +
> +    </sect2>
> +
>    </sect1>
>  
>    <!-- ================================================================= -->
> 

-- 
Arfrever Frehtes Taifersar Arahesis
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://www.red-bean.com/pipermail/svnbook-dev/attachments/20080616/57b3286d/attachment-0001.sig>