svn-best-practices.html revision 299742
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"> 29h1 { 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 40Subversion 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 46and tags are ordinary directories, you'll need to account for them in 47your repository structure.</p> 48 49<p>The Subversion project officially recommends the idea of a "project 50root", which represents an anchoring point for a project. A "project 51root" contains exactly three subdirectories: <tt>/trunk</tt>, 52<tt>/branches</tt>, and <tt>/tags</tt>. A repository may contain 53only 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 66reflects a single purpose: the fixing of a specific bug, the addition 67of a new feature, or some particular task. Your commit will create a 68new revision number which can forever be used as a "name" for the 69change. You can mention this revision number in bug databases, or use 70it as an argument to <tt>svn merge</tt> should you want to undo the 71change 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 81and 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 98descriptive log message that explains what was merged, something 99like:</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 115mix and match older versions of things with newer ones. But there are 116few facts you must be aware of:</p> 117 118<ol> 119 120<li>After every <tt>svn commit</tt>, your working copy has mixed 121revisions. The things you just committed are now at the HEAD 122revision, 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 147to the size of files it can handle. Files are sent "streamily" in 148both directions between Subversion client and server, using a small, 149constant amount of memory on each side of the network.</p> 150 151<p>Of course, there are a number of practical issues to consider. 152While 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 154tremendous amount of both time and space (e.g. files that are dozens 155or hundreds of megabytes large.)</p> 156 157<p>To begin with, remember that your Subversion working copy stores 158pristine copies of all version-controlled files in the 159<tt>.svn/text-base/</tt> area. This means that your working copy 160takes up at least twice as much disk space as the original dataset. 161Beyond that, the Subversion client follows a (currently unadjustable) 162algorithm 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, 179you'll need to be aware that very large files may require quite a bit 180of patient waiting while your client chugs away. You can rest 181assured, however, that unlike CVS, your large files won't incapacitate 182the 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 189culture of your software project. Rather than prescribe a universal 190policy, 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 199functional tests) when a user begins to commit a series of complicated 200changes.</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 210Subversion than in CVS. Because Subversion commits are atomic, it's 211not possible for a checkout or update to receive a "partial" commit 212while 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 243all times. Committers who violate this rule are publically 244humiliated.</li> 245 246<li>Rule #2: a single commit (changeset) must not be so large 247so as to discourage peer-review.</li> 248 249<li>Rule #3: if rules #1 and #2 come into conflict (i.e. it's 250impossible to make a series of small commits without disrupting the 251trunk), then the user should create a branch and commit a series of 252smaller changesets there. This allows peer-review without disrupting 253the 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 267Mapping CVS tasks to SVN tasks 268============================== 269 270This section is just a re-indexing of topics covered in the book, 271for people who prefer to learn from the "bottom up" rather than "top down". 272It shows some common CVS operations, and then the equivalent SVN operation, 273followed 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 291TAGS: 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 306BRANCHES: 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> 319