contrib/subversion/doc/user/svn-best-practices.html

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