doc/user/svn-best-practices.html

   1 <html>
   2 <head>
   3 <title>Subversion Best Practices</title>
   4 </head>
   5
   6 <body>
   7
   8 <center>
   9  <h1>Subversion Best Practices</h1>
  10 </center>
  11
  12 <p>This is a quick set of guidelines for making the best use of
  13 Subversion in your day-to-day software development work.</p>
  14
  15
  16 <h2>Use a sane repository layout</h2>
  17
  18 <p>There are many ways to lay out your repository.  Because branches
  19 and tags are ordinary directories, you'll need to account for them in
  20 your repository structure.</p>
  21
  22 <p>The Subversion project officially recommends the idea of a "project
  23 root", which represents an anchoring point for a project.  A "project
  24 root" contains exactly three subdirectories: <tt>/trunk</tt>,
  25 <tt>/branches</tt>, and <tt>/tags</tt>.  A repository may contain
  26 only one project root, or it may contain a number of them.</p>
  27
  28 <p><em>Book reference:</em> <a
  29         href="http://svnbook.red-bean.com/svnbook/ch05s04.html#svn-ch-5-sect-6.1">Choosing
  30         a Repository Layout</a>.</p>
  31
  32
  33
  34 <!-- =================================================== -->
  35
  36 <h2>Commit logical changesets</h2>
  37
  38 <p>When you commit a change to the repository, make sure your change
  39 reflects a single purpose: the fixing of a specific bug, the addition
  40 of a new feature, or some particular task.  Your commit will create a
  41 new revision number which can forever be used as a "name" for the
  42 change.  You can mention this revision number in bug databases, or use
  43 it as an argument to <tt>svn merge</tt> should you want to undo the
  44 change or port it to another branch.</p>
  45
  46 <p><em>Book reference:</em> "Subversion and Changesets" sidebar,
  47         within <a
  48         href="http://svnbook.red-bean.com/svnbook/ch04s03.html">chapter
  49         4</a>.</p>
  50
  51 <!-- =================================================== -->
  52
  53 <h2>Use the issue-tracker wisely</h2>
  54
  55 <p>Try to create as many two-way links between Subversion changesets
  56 and your issue-tracking database as possible:</p>
  57
  58 <ul>
  59 <li>If possible, refer to a specific issue ID in every commit log message.</li>
  60 <li>When appending information to an issue (to describe progress, or
  61     to close the issue) name the revision number(s) responsible
  62     for the change.</li>
  63 </ul>
  64
  65 <!-- =================================================== -->
  66
  67 <h2>Track merges manually</h2>
  68
  69 <p>When committing the result of a merge, be sure to write a
  70 descriptive log message that explains what was merged, something
  71 like:</p>
  72
  73   <pre>Merged revisions 3490:4120 of /branches/foobranch to /trunk.</pre>
  74
  75 <p><em>Book reference:</em> <a
  76         href="http://svnbook.red-bean.com/svnbook/ch04s03.html#svn-ch-4-sect-3.2">Tracking
  77         merges manually</a>, and <a
  78         href="http://svnbook.red-bean.com/svnbook/ch04s04.html#svn-ch-4-sect-4.1">Merging a whole branch to another</a>.</p>
  79
  80 <!-- =================================================== -->
  81
  82 <h2>Understand mixed-revision working copies</h2>
  83
  84 <p>Your working copy's directories and files can be at different
  85 "working" revisions: this is a deliberate feature which allows you to
  86 mix and match older versions of things with newer ones.  But there are
  87 few facts you must be aware of:</p>
  88
  89 <ol>
  90
  91 <li>After every <tt>svn commit</tt>, your working copy has mixed
  92 revisions.  The things you just committed are now at the HEAD
  93 revision, and everything else is at an older revision.</li>
  94
  95 <li>Certain commits are disallowed:
  96    <ul>
  97      <li>You cannot commit the deletion of a file or directory which
  98      doesn't have a working revision of HEAD.</li>
  99      <li>You cannot commit a property change to a directory which
 100      doesn't have a working revision of HEAD.</li>
 101    </ul>
 102 </li>
 103
 104 <li><tt>svn update</tt> will bring your entire working copy to one
 105             working revision, and is the typical solution to the
 106             problems mentioned in point #2.</li>
 107 </ol>
 108
 109 <p><em>Book reference:</em> <a
 110 href="http://svnbook.red-bean.com/svnbook/ch02s03.html#svn-ch-2-sect-3.4">The
 111             limitation of mixed revisions</a>.</p>
 112
 113
 114 <!-- =================================================== -->
 115
 116 <h2>Be patient with large files</h2>
 117
 118 <p>A nice feature of Subversion is that by design, there is no limit
 119 to the size of files it can handle.  Files are sent "streamily" in
 120 both directions between Subversion client and server, using a small,
 121 constant amount of memory on each side of the network.</p>
 122
 123 <p>Of course, there are a number of practical issues to consider.
 124 While there's no need to worry about files in the kilobyte-sized range
 125 (e.g. typical source-code files), committing larger files can take a
 126 tremendous amount of both time and space (e.g. files that are dozens
 127 or hundreds of megabytes large.)</p>
 128
 129 <p>To begin with, remember that your Subversion working copy stores
 130 pristine copies of all version-controlled files in the
 131 <tt>.svn/text-base/</tt> area.  This means that your working copy
 132 takes up at least twice as much disk space as the original dataset.
 133 Beyond that, the Subversion client follows a (currently unadjustable)
 134 algorithm for committing files:</p>
 135
 136    <ul>
 137      <li>Copies the file to <tt>.svn/tmp/</tt>  <em>(can take a while,
 138           and temporarily uses extra disk space)</em>)</li>
 139
 140      <li>Performs a binary diff between the tmpfile and the pristine
 141           copy, or between the tmpfile and an empty-file if newly
 142           added.  <em>(can take a very long time to compute, even
 143           though only a small amount of data might ultimately be sent
 144           over the network)</em></li>
 145
 146      <li>Sends the diff to the server, then moves the tmpfile into
 147         <tt>.svn/text-base/</tt></li>
 148    </ul>
 149
 150 <p>So while there's no theoretical limit to the size of your files,
 151 you'll need to be aware that very large files may require quite a bit
 152 of patient waiting while your client chugs away.  You can rest
 153 assured, however, that unlike CVS, your large files won't incapacitate
 154 the server or affect other users.</p>
 155
 156 <!-- =================================================== -->
 157
 158 <h2>Work around commands that don't understand copies/renames</h2>
 159
 160 <p>When a file or directory is copied or renamed, the Subversion repository
 161 tracks that history.  Unfortunately in Subversion 1.0, the only client
 162 subcommand which actually takes advantage of this feature is <tt>svn
 163 log</tt>.  A number of other commands (such as <tt>svn diff</tt> and
 164 <tt>svn cat</tt>) ought to be automatically following rename-history,
 165 but aren't doing so yet.</p>
 166
 167 <p>In all of these cases, a basic workaround is to use <tt>'svn log
 168 -v'</tt> to discover the proper path within the older revision.</p>
 169
 170 <p>For example, suppose you copied <tt>/trunk</tt> to
 171 <tt>/branches/mybranch</tt> in revision 200, and then committed some
 172 changes to <tt>/branches/mybranch/foo.c</tt> in subsequent revisions.
 173 Now you'd like to compare revisions 80 and 250 of the file.</p>
 174
 175 <p>If you have a working copy of the branch and run <tt>svn diff
 176 -r80:250 foo.c</tt>, you'll see an error about
 177 <tt>/branches/mybranch/foo.c</tt> not existing in revision 80.  To
 178 remedy, you would run <tt>svn log -v</tt> on your branch or file to
 179 discover that it was named <tt>/trunk/foo.c</tt> prior to revision 200,
 180 and then compare the two URLs directly:</p>
 181
 182 <pre>
 183    $ svn diff http://.../trunk/foo.c@80 \
 184               http://.../branches/mybranch/foo.c@200
 185 </pre>
 186
 187
 188
 189 <!-- =================================================== -->
 190
 191 <h2>Know when to create branches</h2>
 192
 193 <p>This is a hotly debated question, and it really depends on the
 194 culture of your software project.  Rather than prescribe a universal
 195 policy, we'll describe three common ones here.</p>
 196
 197 <h3>The Never-Branch system</h3>
 198
 199 <p>(Often used by nascent projects that don't yet have runnable code.)</p>
 200
 201 <ul>
 202 <li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
 203 <li>Occasionally <tt>/trunk</tt> "breaks" (doesn't compile, or fails
 204 functional tests) when a user begins to commit a series of complicated
 205 changes.</li>
 206 </ul>
 207
 208 <p><em>Pros:</em> Very easy policy to follow.  New developers have low
 209         barrier to entry.  Nobody needs to learn how to branch or merge.</p>
 210
 211 <p><em>Cons:</em> Chaotic development, code could be unstable at any
 212         time.</p>
 213
 214 <p>A side note: this sort of development is a bit less risky in
 215 Subversion than in CVS.  Because Subversion commits are atomic, it's
 216 not possible for a checkout or update to receive a "partial" commit
 217 while somebody else is in the process of committing.</p>
 218
 219
 220 <h3>The Always-Branch system</h3>
 221
 222 <p>(Often used by projects that favor heavy management and supervision.)</p>
 223
 224 <ul>
 225 <li>Each user creates/works on a private branch for <em>every</em> coding task.
 226     </li>
 227 <li>When coding is complete, someone (original coder, peer, or
 228     manager) reviews all private branch changes and merges them to
 229     <tt>/trunk</tt>.</li>
 230 </ul>
 231
 232 <p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be
 233        <em>extremely</em> stable at all times. </p>
 234
 235 <p><em>Cons:</em> Coders are artificially isolated from each other,
 236           possibly creating more merge conflicts than necessary.
 237           Requires users to do lots of extra merging.</p>
 238
 239
 240 <h3>The Branch-When-Needed system</h3>
 241
 242 <p>(This is the system used by the Subversion project.)
 243
 244 <ul>
 245 <li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
 246
 247 <li>Rule #1: <tt>/trunk</tt> must compile and pass regression tests at
 248 all times.  Committers who violate this rule are publically
 249 humiliated.</li>
 250
 251 <li>Rule #2: a single commit (changeset) must not be so large
 252 so as to discourage peer-review.</li>
 253
 254 <li>Rule #3: if rules #1 and #2 come into conflict (i.e. it's
 255 impossible to make a series of small commits without disrupting the
 256 trunk), then the user should create a branch and commit a series of
 257 smaller changesets there.  This allows peer-review without disrupting
 258 the stability of <tt>/trunk</tt>.</li>
 259
 260 </ul>
 261
 262 <p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be stable at all
 263        times.  The hassle of branching/merging is somewhat rare.</p>
 264
 265 <p><em>Cons:</em> Adds a bit of burden to users' daily work:
 266           they must compile and test before every commit.</p>
 267
 268
 269 <!--
 270
 271
 272 Mapping CVS tasks to SVN tasks
 273 ==============================
 274
 275 This section is just a re-indexing of topics covered in the book,
 276 for people who prefer to learn from the "bottom up" rather than "top down".
 277 It shows some common CVS operations, and then the equivalent SVN operation,
 278 followed by a link to the book which explains more.
 279
 280
 281 * Importing data.
 282
 283 * Checking out a working copy.
 284
 285 * Seeing your changes.
 286
 287 * Undoing your changes.
 288
 289 * Resolving a conflict.
 290
 291 * Adding binary files.
 292
 293 * Activating keyword expansion and/or EOL translation.
 294
 295
 296 TAGS:
 297
 298 * Creating a tag from a working copy
 299
 300 * Creating a remote tag
 301
 302 * Seeing all of a project's tags
 303
 304 * Comparing two tags
 305
 306 * Seeing the logs between two tags
 307
 308 * Tweaking a tag
 309
 310
 311 BRANCHES:
 312
 313 * Creating a branch and switching to it
 314
 315 * Finding the beginning of a branch
 316
 317 * Merging a branch to trunk, or vice versa
 318
 319 -->
 320
 321
 322 </body>
 323 </html>