www/release-process.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <style type="text/css"> /* <![CDATA[ */
   7   @import "branding/css/tigris.css";
   8   @import "branding/css/inst.css";
   9   /* ]]> */</style>
  10 <link rel="stylesheet" type="text/css" media="print"
  11   href="branding/css/print.css" />
  12 <script type="text/javascript" src="branding/scripts/tigris.js"></script>
  13 <title>The Subversion Release Procedure</title>
  14 </head>
  15
  16 <body>
  17 <div class="app">
  18
  19 <h1 style="text-align: center;">The Subversion Release Procedure</h1>
  20
  21 <p>If you are the current Release Manager for the Subversion project,
  22 or aspire to be, you should read and follow this procedure.</p>
  23
  24 <pre>
  25 $LastChangedDate: 2006-04-03 18:57:54 +0200 (Mon, 03 Apr 2006) $
  26 </pre>
  27
  28
  29 <!-- Other pages seem to use "h2" for ToC, but I think "h1" works
  30      better, because the ToC is fundamentally different from other
  31      sections and therefore it's confusing when it looks the same as
  32      the others. -->
  33 <div class="h1"><!-- no 'id' or 'title' attribute for ToC -->
  34 <h1>Table of Contents</h1>
  35
  36 <ol id="toc">
  37   <li><a href="#release-manager-role">Being the Release Manager</a></li>
  38   <li><a href="#release-branches">Creating and maintaining release branches</a></li>
  39   <li><a href="#porting-changes">Porting changes to release branches</a></li>
  40   <li><a href="#the-changes-file">Managing the <tt>CHANGES</tt> file</a>
  41   <ol>
  42     <li><a href="#writing-initial-changes">Writing the initial content for a branch</a></li>
  43     <li><a href="#adding-changes">Adding content for patch release</a></li>
  44   </ol>
  45   </li> <!-- the-changes-file -->
  46   <li><a href="#before-release">Preparing to roll a release</a></li>
  47   <li><a href="#rolling-release">Rolling a release</a></li>
  48   <li><a href="#blessing-release">Blessing a release</a></li>
  49   <li><a href="#releasing-release">The actual releasing</a></li>
  50   <li><a href="#afterwards">After a release has been made</a></li>
  51 </ol>
  52
  53 </div> <!-- h1 -->
  54
  55
  56 <div class="h2" id="release-manager-role" title="release-manager-role">
  57 <h2>Being the Release Manager</h2>
  58
  59 <p>The role of the Release Manager in the Subversion project is to
  60 handle the process of getting code stabilized, packaged and released
  61 to the general public.  If we were building planes, the RM would be
  62 the guy looking at the construction checklists, painting the airline
  63 logo on the fuselage, and delivering the finished unit to the
  64 customer.</p>
  65
  66 <p>As such, there is no real development associated with being an RM.
  67 All the work you have to do is non-coding: coordinating people,
  68 centralizing information, and being the public voice announcing new
  69 stable releases.  A lot of the tasks that the RM has to do are
  70 repetitive, and not automated either because nobody has broken down
  71 and written the tools yet, or because the tasks require human
  72 validation that makes automation a little superfluous.</p>
  73
  74 <p>You may be thinking at this stage that the RM's duty is
  75 unglamorous, and you are kinda right.  If you are looking for a
  76 position within the project that will bring fame and fortune, you're
  77 better off implementing stuff that really needs to be done on trunk.
  78 If you're looking for something that really helps people who don't
  79 care about releases focus on code, then RMing is for you.</p>
  80
  81 <p>So, you are the Release Manager.  What do you need to do?  This is
  82 what the rest of this document is about.</p>
  83
  84 </div> <!-- release-manager-role -->
  85
  86
  87 <div class="h2" id="release-branches" title="release-branches">
  88 <h2>Creating and maintaining release branches</h2>
  89
  90 <p>A new release branch is created for each new major and minor
  91 release.  So, for example, a new release branch is created when
  92 preparing to release version 2.0.0, or version 1.3.0.  However, when
  93 preparing to release 1.3.1 (a patch-version increment), the release
  94 branch created at the time of 1.3.0 is used.</p>
  95
  96 <p>If you are preparing for a patch release, then there is no release
  97 branch to create. You just pick up where you left off in the current
  98 minor version series release branch.</p>
  99
 100 <p>The time at which a new release branch needs to be created is fuzzy
 101 at best.  Generally, we have a soft schedule of releasing a new minor
 102 version every 6 months.  So, approximately 4 months after the previous
 103 minor release is a good time to start proposing a branch. But remember
 104 that this is flexible, depending on what features are being
 105 developed.</p>
 106
 107 <p>Once people agree that a new release branch should be made, the
 108 Release Manager creates it with the following procedure (substitute
 109 A.B with the version you're preparing, eg. 1.3, or 2.0):</p>
 110
 111 <ul>
 112 <li><p>Create the new release branch with a server-side copy:</p>
 113     <pre>
 114       svn cp http://svn.collab.net/repos/svn/trunk \
 115              http://svn.collab.net/repos/svn/branches/A.B.x \
 116              -m "Create A.B.x release branch."
 117     </pre></li>
 118
 119 <li><p>Edit <tt>subversion/include/svn_version.h</tt> on trunk and
 120     increment the version numbers there.  Do not commit these changes
 121     yet.</p>
 122     <p>The version number on trunk always reflects the major/minor
 123     version that will immediately follow the one for which you just
 124     created a branch (eg. 2.1.0 for the 2.0.x branch, and 1.4.0 for
 125     the 1.3.x branch).</p></li>
 126
 127 <li><p>Edit <tt>CHANGES</tt> on trunk to introduce a new section for the
 128     upcoming release.  The section starts with:</p>
 129     <pre>
 130       Version A.B.0 (released ?? ????? 200X, from /branches/A.B.x)
 131       http://svn.collab.net/repos/svn/tags/A.B.0
 132     </pre>
 133     <p>Leave the release date blank for now. It will remain this way
 134     until rolling time.</p></li>
 135
 136 <li><p>Commit both these changes with the following log message:</p>
 137     <pre>
 138       Increment the trunk version number, and introduce a new CHANGES
 139       section for the upcoming A.B.0 release.
 140
 141       * subversion/include/svn_version.h: Increment version number.
 142
 143       * CHANGES: New section for A.B.0.
 144     </pre></li>
 145 </ul>
 146
 147 </div> <!-- release-branches -->
 148
 149
 150 <div class="h2" id="porting-changes" title="porting-changes">
 151 <h2>Porting changes to release branches</h2>
 152
 153 <p>Once a release branch has been created, no development <i>ever</i>
 154 takes place there.  The only changes permitted are ones made to
 155 various bookkeeping files such as <tt>STATUS</tt>, and changes merged
 156 in from trunk.</p>
 157
 158 <p>The protocol used to accept or refuse the merging of changes from
 159 trunk is of interest to all Subversion developers, and as such is
 160 documented in <a href="hacking.html#release-stabilization">the
 161 release stabilization section of the hacking guide</a>.</p>
 162
 163 </div> <!-- porting-changes -->
 164
 165
 166 <div class="h2" id="the-changes-file" title="the-changes-file">
 167 <h2>Managing the <tt>CHANGES file</tt></h2>
 168
 169 <p>The <tt>CHANGES</tt> file is the project changelog file.  Before a
 170 release, it must be brought up to date to list all changes since the
 171 last release.</p>
 172
 173 <p>For patch-releases, this is fairly easy: you just need to walk
 174 through the commit logs for the branch since the last "golden"
 175 revision, and note all interesting merges.  For minor and major
 176 releases, this is more complex: you need to traverse the commit log on
 177 <em>trunk</em> since the last release branch was forked, and make note
 178 of all changes there.  It's the same procedure, but a lot longer, and
 179 somewhat more complex as it involves filtering out changesets that
 180 have already been backported to previous release branches and released
 181 from there.</p>
 182
 183 <p>Remember that <tt>CHANGES</tt> should <em>always</em> be edited on
 184 trunk and then merged over to the release branch(es) when necessary.
 185 It is very important that all changes of all releases be documented in
 186 the <tt>CHANGES</tt> file on trunk, both for future reference and so that
 187 future release branches contain the sum of all previous change
 188 logs.</p>
 189
 190 <p>Keep the bullet point for each change concise, preferably no more
 191 than one line long.  Sometimes that can be a challenge, but it really
 192 adds to the overall readability of the document.  Think to yourself:
 193 <i>If it takes more than one line to describe, maybe I'm getting too
 194 detailed?</i></p>
 195
 196 <div class="h3" id="writing-initial-changes" title="writing-initial-changes">
 197 <h3>Writing the initial content for a branch</h3>
 198
 199 <p>Run <code>svn log -rHEAD:BRANCH_POINT
 200 http://svn.collab.net/repos/svn/branches/A.B.x</code>,where
 201 BRANCH_POINT is the revnum where the previous major/minor release was
 202 branched off of the trunk.  This should give you every change ever
 203 made to the A.B.x line, including backports made to the A.B.x branch.
 204 You then need to <em>remove</em> logs of changes that have already
 205 been released in micro releases of the previous major/minor branch.
 206 Run <code>svn log -q --stop-on-copy</code> on the previous release
 207 branch, and then write a script to parse the revnums and remove them
 208 from your primary log output.  (Karl and Ben used to use emacs macros
 209 to do that, but suggest that we write a more general script.)</p>
 210
 211 <p>Read that log from oldest to newest, summarizing points as you go.
 212 The trick is to know what level of detail to write at: you don't want
 213 to mention every tiny little commit, but you don't want to be too
 214 general either.  Set your filter-level by reading through a few pages
 215 of the <tt>CHANGES</tt> file before starting on the new section, just to
 216 keep things consistent.</p>
 217
 218 </div> <!-- writing-initial-changes -->
 219
 220 <div class="h3" id="adding-changes">
 221 <h3>Adding content for patch release</h3>
 222
 223 <p>As part of <a href="/hacking.html#release-stabilization">release
 224 stabilization</a>, <tt>CHANGES</tt> should be updated as bug fixes are
 225 ported to the release branch.  Generally, if you merge a revision or group
 226 of revisions (i.e., an item in <tt>STATUS</tt>) to the release branch, you
 227 should also add an item to <tt>CHANGES</tt> on trunk, following the same
 228 guidelines outlined above.  This list will then be merged to the release
 229 branch when a patch release is made.</p>
 230
 231 </div> <!-- adding-changes -->
 232
 233 </div> <!-- the-changes-file -->
 234
 235
 236 <div class="h2" id="before-release" title="before-release">
 237 <h2>Preparing to roll a release</h2>
 238
 239 <p>So, a release branch has stabilized, and you are gearing up to roll
 240 the release.  Before you can actually roll the archives, you need to
 241 set up a white-room rolling environment.  This environment must
 242 contain pristine versions of some build tools, as well as all the
 243 relevant dependancies and other stuff that gets bundled into a
 244 release tarball.</p>
 245
 246 <p>You need to grab vanilla source tarballs of the following build
 247 tools before proceeding:</p>
 248
 249 <ul>
 250 <li><p><b>Autoconf</b> 2.59 (2.60 is a significant compatibility break
 251 from the 2.5x series, and is known to break APR)</p></li>
 252 <li><p><b>Libtool</b> 1.5.22</p></li>
 253 <li><p><b>SWIG</b> 1.3.25</p></li>
 254 </ul>
 255
 256 <p>It is important that you do not use distribution shipped versions
 257 of this software as they are often patched in ways that are not
 258 portable.  The version numbers given above should normally be
 259 reconsidered and increased to the latest stable upstream release in
 260 the time leading up to an A.B.0 release.  Changing the version within
 261 an A.B.x series should only be done with careful considereration.</p>
 262
 263 <p>Also grab the following source tarballs, parts of which will be
 264 bundled in the Subversion release packages:</p>
 265
 266 <ul>
 267 <li><p>The latest Unix <b>APR</b> and <b>APR-util</b> of the 0.9.x
 268 line (currently 0.9.13)</p></li>
 269 <li><p>The latest Win32 <b>APR</b>, <b>APR-util</b> and
 270 <b>APR-iconv</b> of the 0.9.x line (currently 0.9.13)</p></li>
 271 <li><p>The latest <b>Neon</b> 0.25.x release (currently
 272 0.25.5)</p></li>
 273 <li><p>The latest <b>zlib</b> release (currently 1.2.3)</p></li>
 274 </ul>
 275
 276 <p>Once you have all this, you can start the following procedure.
 277 When it is done, you will have a build environment ready to roll
 278 tarballs.</p>
 279
 280 <p><b>Autoconf, Libtool and SWIG</b>: Pick a directory to contain your
 281 special build tools for Subversion RM duties - for example
 282 <tt>/opt/svnrm</tt>.  Configure, build and install the three pieces of
 283 software with <tt>--prefix=/opt/svnrm</tt>, and remember, whenever you
 284 run <tt>dist.sh</tt> to be sure that <tt>/opt/svnrm/bin</tt> is at the
 285 front of your <tt>PATH</tt>.</p>
 286
 287 <p><b>Dependency source preparation</b>: You should create two
 288 directories which will hold the dependencies which will be repackaged
 289 with Subversion, one for Unix and one for Win32.  You might, for
 290 example, choose <tt>/opt/svnrm/unix-dependencies</tt> and
 291 <tt>/opt/svnrm/win32-dependencies</tt>.  Within the Unix one, you must
 292 unpack the Unix APR and APR-util tarballs, and the Neon and zlib
 293 tarballs, and then rename each top level directory so it does
 294 <b>not</b> contain a version number, resulting in a directory
 295 containing four directories: <tt>apr</tt>, <tt>apr-util</tt>,
 296 <tt>neon</tt> and <tt>zlib</tt>.  Within the Win32 one, you must
 297 unpack the Apache HTTP Server zipfile, move the <tt>apr</tt>,
 298 <tt>apr-util</tt> and <tt>apr-iconv</tt> directories from the
 299 <tt>srclib</tt> directory of the <tt>httpd</tt> zipfile into the
 300 dependency directory, and delete the rest of the <tt>httpd</tt>
 301 extract.  You must then copy the <tt>neon</tt> and <tt>zlib</tt>
 302 directories from the Unix dependency directory into the Win32 one too.
 303 Do not use symlinks, <tt>dist.sh</tt> does not support them.</p>
 304
 305 </div> <!-- before-release -->
 306
 307
 308 <div class="h2" id="rolling-release" title="rolling-release">
 309 <h2>Rolling a release</h2>
 310
 311 <p>Before rolling, first make sure that the latest version of the
 312 <tt>CHANGES</tt> file from trunk is merged into the release branch, and that
 313 the date at the top of <tt>CHANGES</tt> matches the planned release date of
 314 the tarball.</p>
 315
 316 <p><b>Build the tarballs</b>: From within your Unix dependency
 317 directory, run:</p>
 318 <pre>
 319 PATH="/opt/svnrm/bin:$PATH" ./dist.sh -v X.Y.Z -r 1234 -pr branches/X.Y.Z
 320 </pre>
 321 <p>Watch <tt>dist.sh</tt>'s output to make sure everything goes
 322 smoothly; when it's done, you'll have tarballs in the cwd.</p>
 323
 324 <p><b>Build the zipfiles</b>: From within your Win32 dependency
 325 directory, run:</p>
 326 <pre>
 327 PATH="/opt/svnrm/bin:$PATH" ./dist.sh -v X.Y.Z -r 1234 -pr branches/X.Y.Z -zip
 328 </pre>
 329 <p>Watch <tt>dist.sh</tt>'s output to make sure everything goes
 330 smoothly; when it's done, you'll have zipfiles in the cwd.</p>
 331
 332 <pre>
 333 Test one or both of the tarballs:
 334
 335     a) tar zxvf subversion-X.Y.Z.tar.gz;  cd subversion-X.Y.Z
 336     b) ./configure
 337
 338        See INSTALL, section III.B for detailed instructions on
 339        configuring/building Subversion.
 340
 341        If you installed Apache in some place other than the default, as
 342        mentioned above, you will need to use the same
 343        --prefix=/usr/local/apache2 option as used to configure Apache.
 344
 345        You may also want to use --enable-mod-activation, which will
 346        automatically enable the required Subversion modules in the
 347        Apache config file.
 348
 349     c) make
 350     d) make check
 351     e) make install (this activates mod_dav)
 352     f) make davcheck
 353
 354        For this, start up Apache after having configured according to
 355        the directions in subversion/tests/cmdline/README.
 356
 357        Make sure, that if you maintain a development installation of
 358        apache, that you check the config file and update it for the
 359        new release area where you're testing the tar-ball.
 360
 361        (Unless you rename the tree which gets extracted from the
 362        tarball to match what's in httpd.conf, you will need to edit
 363        httpd.conf)
 364
 365     g) make svncheck
 366
 367        First, start up svnserve with these args:
 368
 369           $ subversion/svnserve/svnserve -d -r \
 370             `pwd`/subversion/tests/cmdline
 371
 372        -d tells svnserve to run as a daemon
 373        -r tells svnserve to use the following directory as the
 374           logical file system root directory.
 375
 376        After svnserve is running as a daemon 'make svncheck' should run
 377
 378     h) Then test that you can check out the Subversion repository
 379        with this environment:
 380
 381           subversion/svn/svn co https://svn.collab.net/repos/svn/trunk
 382
 383     i) Verify that the perl and python swig bindings at least compile.
 384        If you can't do this, then have another developer verify.
 385
 386        (see bindings/swig/INSTALL for details)
 387
 388        Ensure that ./configure detected a suitable version of swig,
 389        perl, and python.  Then:
 390
 391           make swig-py
 392           make check-swig-py
 393           sudo make install-swig-py
 394
 395           make swig-pl
 396           make check-swig-pl
 397           sudo make install-swig-pl
 398
 399     j) Verify that the javahl bindings at least compile.
 400        If you can't do this, then have another developer verify.
 401
 402        (see bindings/java/javahl/README for details)
 403
 404        Ensure that ./configure detected a suitable jdk, and then
 405        possibly re-run with '--enable-javahl' and '--with-jdk=':
 406
 407           make javahl
 408           sudo make install-javahl
 409           make check-javahl
 410 </pre>
 411
 412 <p><b>Use GnuPG to sign release:</b></p>
 413 <pre>
 414     gpg -ba subversion-X.Y.Z.tar.bz2
 415     gpg -ba subversion-X.Y.Z.tar.gz
 416     gpg -ba subversion-X.Y.Z.zip
 417     gpg -ba subversion-deps-X.Y.Z.tar.bz2
 418     gpg -ba subversion-deps-X.Y.Z.tar.gz
 419     gpg -ba subversion-deps-X.Y.Z.zip
 420 </pre>
 421
 422 </div> <!-- rolling-release -->
 423
 424
 425 <div class="h2" id="blessing-release" title="blessing-release">
 426 <h2>Blessing a release</h2>
 427 </div> <!-- blessing-release -->
 428
 429
 430 <div class="h2" id="releasing-release" title="releasing-release">
 431 <h2>The actual releasing</h2>
 432
 433 <p><b>Subversion Operations</b></p>
 434 <p>Create the tag with the svn_version.h that reflects the final
 435 release.  You do this by updating your working copy to the release
 436 revision, 1234 in the example below.  Run svnversion to verify that
 437 you do not have a mixed working copy or modified working copy, i.e.
 438 svnversion outputs only the release revision (not 1234:1235 or 1234M).
 439 Then place the svn_version.h.dist file in place in the working copy
 440 and copy from the working copy to the tag URL.  For example:</p>
 441
 442 <pre>
 443     svn up -r 1234
 444     svnversion .
 445     cp svn_version.h.dist subversion/include/svn_version.h
 446     svn cp . \
 447            https://svn.collab.net/repos/svn/tags/X.Y.Z \
 448            -m "Tagging release X.Y.Z with svn_version.h matching tarball"
 449 </pre>
 450
 451 <p>Note: Please always make a tag, even for release candidates.</p>
 452
 453 <p>Bump the svn_version.h for the original branch.  If you just did
 454 1.0.2 then svn_version.h should have the proper values for 1.0.3 and
 455 so on.</p>
 456
 457 <p><b>Upload the tarballs to
 458   http://subversion.tigris.org/downloads/.</b></p>
 459 <p>The RM will be given details on how to do this via private
 460 channels.</p>
 461
 462 <p><b>Update Tigris "Documents &amp; files" area</b></p>
 463 <p>Update the links to the tarballs in the Documents &amp; files
 464 Tigris webapp.</p>
 465
 466 <ol>
 467   <li>Log into <a href="http://subversion.tigris.org/">Tigris</a></li>
 468   <li>Click on 'Documents &amp; files'.</li>
 469   <li>Navigate to the 'subversion/Releases/Source code/' folder.</li>
 470   <li>For each of the 12 files:
 471   <ol>
 472     <li>Click on the 'Add new file' link.</li>
 473     <li>Fill in the following fields:
 474     <ul>
 475       <li>Name: &lt;file name&gt;</li>
 476       <li>Status: Stable</li>
 477       <li>Description: <i>(one of:)</i>
 478       <ul>
 479         <li>Subversion release X.Y.Z (MD5: &lt;md5sum of
 480         tarball&gt;)</li>
 481         <li>Subversion dependencies X.Y.Z (MD5: &lt;md5sum of
 482         tarball&gt;)</li>
 483         <li>PGP Signatures for Subversion release X.Y.Z.</li>
 484       </ul>
 485       </li>
 486       <li>Contents: <i>(choose 'Link', then enter:)</i>
 487       http://subversion.tigris.org/downloads/&lt;file name&gt;
 488       </li>
 489     </ul>
 490     </li>
 491     <li>Click Submit.</li>
 492   </ol>
 493   </li>
 494 </ol>
 495
 496 <p><b>Announcements</b></p>
 497 <p>Write a release announcement, referring to previous ones for
 498 guidance.  Remember to include the URL and MD5 checksums in the
 499 announcement!</p>
 500
 501 <p>Post a project news item <a
 502 href="http://subversion.tigris.org/servlets/ProjectNewsList">here</a>.
 503 If the link reads "Suggest an announcement" instead of "Add new
 504 announcement", then you do not have the required permission - ask to
 505 be granted the 'Release Manager' Tigris role.  Note that the
 506 Tigris news items are in HTML format not plain text.</p>
 507
 508 <p>Send an announcement to dev@, users@, and announce@ lists.  Ensure
 509 that your mailer doesn't wrap the URLs over multiple lines.</p>
 510
 511 <p>You should also notify freshmeat of the new release.  You need to
 512 be listed as a release manager or admin for the <a
 513 href="http://freshmeat.net/projects/subversion/">Subversion project
 514   on Freshmeat</a>.  Contact one of the folks who are already listed
 515 if you need access.  Your submission will also be tweaked by the
 516 freshmeat crew before it goes public.</p>
 517
 518 <p><b>Update the website</b></p>
 519 <ol>
 520   <li>Edit the www/project_status.html file appropriately in /trunk
 521   *NOT* in the release branch and commit. Remember edit a search term
 522   at the end of release's issue link.</li>
 523   <li>Update the best available version at the top of
 524   www/project_packages.html</li>
 525   <li>Update the "Latest Release" section of www/index.html to point
 526   to the new announcement.</li>
 527   <li>Commit the modifications.</li>
 528 </ol>
 529
 530 <p>If you've made it this far, go and enjoy your $favorite_beverage now.</p>
 531
 532 </div> <!-- releasing-release -->
 533
 534
 535 <div class="h2" id="afterwards" title="afterwards">
 536 <h2>After a release has been made</h2>
 537
 538 <p>When someone with administrative access to <tt>svn.collab.net</tt>
 539 has time available, they will upgrade it to the latest release or
 540 release candidate.  (This person is not usually the release
 541 manager.)</p>
 542
 543 </div> <!-- afterwards -->
 544
 545
 546 </div> <!-- app -->
 547 </body>
 548 </html>