view release on metacpan or  search on metacpan

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

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

<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,
followed by a link to the book which explains more.


* Importing data.

* Checking out a working copy.

* Seeing your changes.

* Undoing your changes.

* Resolving a conflict.

* Adding binary files.

* Activating keyword expansion and/or EOL translation.


TAGS:

* Creating a tag from a working copy

* Creating a remote tag

* Seeing all of a project's tags

* Comparing two tags

* Seeing the logs between two tags

* Tweaking a tag