view release on metacpan or  search on metacpan

src/subversion/doc/user/svn-best-practices.html  view on Meta::CPAN

<h2>Work around commands that don't understand copies/renames</h2>

<p>When a file or directory is copied or renamed, the Subversion repository
tracks that history.  Unfortunately in Subversion 1.0, the only client
subcommand which actually takes advantage of this feature is <tt>svn
log</tt>.  A number of other commands (such as <tt>svn diff</tt> and
<tt>svn cat</tt>) ought to be automatically following rename-history,
but aren't doing so yet.</p>

<p>In all of these cases, a basic workaround is to use <tt>'svn log
-v'</tt> to discover the proper path within the older revision.</p>

<p>For example, suppose you copied <tt>/trunk</tt> to
<tt>/branches/mybranch</tt> in revision 200, and then committed some
changes to <tt>/branches/mybranch/foo.c</tt> in subsequent revisions.
Now you'd like to compare revisions 80 and 250 of the file.</p>

<p>If you have a working copy of the branch and run <tt>svn diff
-r80:250 foo.c</tt>, you'll see an error about
<tt>/branches/mybranch/foo.c</tt> not existing in revision 80.  To
remedy, you would run <tt>svn log -v</tt> on your branch or file to
discover that it was named <tt>/trunk/foo.c</tt> prior to revision 200,
and then compare the two URLs directly:</p>

<pre>
   $ svn diff http://.../trunk/foo.c@80 \
              http://.../branches/mybranch/foo.c@200
</pre>



<!-- =================================================== -->

<h2>Know when to create branches</h2>

<p>This is a hotly debated question, and it really depends on the
culture of your software project.  Rather than prescribe a universal
policy, we'll describe three common ones here.</p>

<h3>The Never-Branch system</h3>

<p>(Often used by nascent projects that don't yet have runnable code.)</p>

<ul>
<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
<li>Occasionally <tt>/trunk</tt> "breaks" (doesn't compile, or fails
functional tests) when a user begins to commit a series of complicated
changes.</li>
</ul>

<p><em>Pros:</em> Very easy policy to follow.  New developers have low
        barrier to entry.  Nobody needs to learn how to branch or merge.</p>

<p><em>Cons:</em> Chaotic development, code could be unstable at any
        time.</p>

<p>A side note: this sort of development is a bit less risky in
Subversion than in CVS.  Because Subversion commits are atomic, it's
not possible for a checkout or update to receive a "partial" commit
while somebody else is in the process of committing.</p>


<h3>The Always-Branch system</h3>

<p>(Often used by projects that favor heavy management and supervision.)</p>

<ul>
<li>Each user creates/works on a private branch for <em>every</em> coding task.
    </li>
<li>When coding is complete, someone (original coder, peer, or
    manager) reviews all private branch changes and merges them to
    <tt>/trunk</tt>.</li>
</ul>

<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be
       <em>extremely</em> stable at all times. </p>

<p><em>Cons:</em> Coders are artificially isolated from each other,
          possibly creating more merge conflicts than necessary.
          Requires users to do lots of extra merging.</p>


<h3>The Branch-When-Needed system</h3>

<p>(This is the system used by the Subversion project.)

<ul>
<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>

<li>Rule #1: <tt>/trunk</tt> must compile and pass regression tests at
all times.  Committers who violate this rule are publically
humiliated.</li>

<li>Rule #2: a single commit (changeset) must not be so large
so as to discourage peer-review.</li>

<li>Rule #3: if rules #1 and #2 come into conflict (i.e. it's
impossible to make a series of small commits without disrupting the
trunk), then the user should create a branch and commit a series of
smaller changesets there.  This allows peer-review without disrupting
the stability of <tt>/trunk</tt>.</li>

</ul>

<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be stable at all
       times.  The hassle of branching/merging is somewhat rare.</p>

<p><em>Cons:</em> Adds a bit of burden to users' daily work:
          they must compile and test before every commit.</p>


<!--


Mapping CVS tasks to SVN tasks
==============================

This section is just a re-indexing of topics covered in the book,
for people who prefer to learn from the "bottom up" rather than "top down".
It shows some common CVS operations, and then the equivalent SVN operation,