docs/HowToReleaseLLVM.rst

   1 =================================
   2 How To Release LLVM To The Public
   3 =================================
   4
   5 .. contents::
   6    :local:
   7
   8 .. sectionauthor:: Tanya Lattner <tonic@nondot.org>,
   9                    Reid Spencer <rspencer@x10sys.com>,
  10                    John Criswell <criswell@cs.uiuc.edu> and
  11                    Bill Wendling <wendling@apple.com>
  12
  13 Introduction
  14 ============
  15
  16 This document contains information about successfully releasing LLVM ---
  17 including subprojects: e.g., ``clang`` and ``dragonegg`` --- to the public.  It
  18 is the Release Manager's responsibility to ensure that a high quality build of
  19 LLVM is released.
  20
  21 .. _timeline:
  22
  23 Release Timeline
  24 ================
  25
  26 LLVM is released on a time based schedule --- roughly every 6 months.  We do
  27 not normally have dot releases because of the nature of LLVM's incremental
  28 development philosophy.  That said, the only thing preventing dot releases for
  29 critical bug fixes from happening is a lack of resources --- testers,
  30 machines, time, etc.  And, because of the high quality we desire for LLVM
  31 releases, we cannot allow for a truncated form of release qualification.
  32
  33 The release process is roughly as follows:
  34
  35 * Set code freeze and branch creation date for 6 months after last code freeze
  36   date.  Announce release schedule to the LLVM community and update the website.
  37
  38 * Create release branch and begin release process.
  39
  40 * Send out release candidate sources for first round of testing.  Testing lasts
  41   7-10 days.  During the first round of testing, any regressions found should be
  42   fixed.  Patches are merged from mainline into the release branch.  Also, all
  43   features need to be completed during this time.  Any features not completed at
  44   the end of the first round of testing will be removed or disabled for the
  45   release.
  46
  47 * Generate and send out the second release candidate sources.  Only *critial*
  48   bugs found during this testing phase will be fixed.  Any bugs introduced by
  49   merged patches will be fixed.  If so a third round of testing is needed.
  50
  51 * The release notes are updated.
  52
  53 * Finally, release!
  54
  55 .. _process:
  56
  57 Release Process
  58 ===============
  59
  60 #. :ref:`Release Administrative Tasks <release-admin>`
  61
  62    #. :ref:`Create Release Branch <branch>`
  63
  64    #. :ref:`Update Version Numbers <verchanges>`
  65
  66 #. :ref:`Building the Release <release-build>`
  67
  68    #. :ref:`Build the LLVM Source Distribution <dist>`
  69
  70    #. :ref:`Build LLVM <build>`
  71
  72    #. :ref:`Build the Clang Binary Distribution <clangbin>`
  73
  74    #. :ref:`Target Specific Build Details <target-build>`
  75
  76 #. :ref:`Release Qualification Criteria <release-qualify>`
  77
  78    #. :ref:`Qualify LLVM <llvm-qualify>`
  79
  80    #. :ref:`Qualify Clang <clang-qualify>`
  81
  82    #. :ref:`Specific Target Qualification Details <target>`
  83
  84 #. :ref:`Community Testing <commTest>`
  85
  86 #. :ref:`Release Patch Rules <release-patch>`
  87
  88 #. :ref:`Release final tasks <release-final>`
  89
  90    #. :ref:`Update Documentation <updocs>`
  91
  92    #. :ref:`Tag the LLVM Final Release <tag>`
  93
  94    #. :ref:`Update the LLVM Demo Page <updemo>`
  95
  96    #. :ref:`Update the LLVM Website <webupdates>`
  97
  98    #. :ref:`Announce the Release <announce>`
  99
 100 .. _release-admin:
 101
 102 Release Administrative Tasks
 103 ----------------------------
 104
 105 This section describes a few administrative tasks that need to be done for the
 106 release process to begin.  Specifically, it involves:
 107
 108 * Creating the release branch,
 109
 110 * Setting version numbers, and
 111
 112 * Tagging release candidates for the release team to begin testing.
 113
 114 .. _branch:
 115
 116 Create Release Branch
 117 ^^^^^^^^^^^^^^^^^^^^^
 118
 119 Branch the Subversion trunk using the following procedure:
 120
 121 #. Remind developers that the release branching is imminent and to refrain from
 122    committing patches that might break the build.  E.g., new features, large
 123    patches for works in progress, an overhaul of the type system, an exciting
 124    new TableGen feature, etc.
 125
 126 #. Verify that the current Subversion trunk is in decent shape by
 127    examining nightly tester and buildbot results.
 128
 129 #. Create the release branch for ``llvm``, ``clang``, the ``test-suite``, and
 130    ``dragonegg`` from the last known good revision.  The branch's name is
 131    ``release_XY``, where ``X`` is the major and ``Y`` the minor release
 132    numbers.  The branches should be created using the following commands:
 133
 134    ::
 135
 136      $ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
 137                 https://llvm.org/svn/llvm-project/llvm/branches/release_XY
 138
 139      $ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
 140                 https://llvm.org/svn/llvm-project/cfe/branches/release_XY
 141
 142      $ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
 143                 https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
 144
 145      $ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
 146                 https://llvm.org/svn/llvm-project/test-suite/branches/release_XY
 147
 148 #. Advise developers that they may now check their patches into the Subversion
 149    tree again.
 150
 151 #. The Release Manager should switch to the release branch, because all changes
 152    to the release will now be done in the branch.  The easiest way to do this is
 153    to grab a working copy using the following commands:
 154
 155    ::
 156
 157      $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
 158
 159      $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
 160
 161      $ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
 162
 163      $ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
 164
 165 .. _verchanges:
 166
 167 Update LLVM Version
 168 ^^^^^^^^^^^^^^^^^^^
 169
 170 After creating the LLVM release branch, update the release branches'
 171 ``autoconf`` and ``configure.ac`` versions from '``X.Ysvn``' to '``X.Y``'.
 172 Update it on mainline as well to be the next version ('``X.Y+1svn``').
 173 Regenerate the configure scripts for both ``llvm`` and the ``test-suite``.
 174
 175 In addition, the version numbers of all the Bugzilla components must be updated
 176 for the next release.
 177
 178 .. _dist:
 179
 180 Build the LLVM Release Candidates
 181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183 Create release candidates for ``llvm``, ``clang``, ``dragonegg``, and the LLVM
 184 ``test-suite`` by tagging the branch with the respective release candidate
 185 number.  For instance, to create **Release Candidate 1** you would issue the
 186 following commands:
 187
 188 ::
 189
 190   $ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY
 191   $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
 192              https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1
 193
 194   $ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY
 195   $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
 196              https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1
 197
 198   $ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY
 199   $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
 200              https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1
 201
 202   $ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY
 203   $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
 204              https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1
 205
 206 Similarly, **Release Candidate 2** would be named ``RC2`` and so on.  This keeps
 207 a permanent copy of the release candidate around for people to export and build
 208 as they wish.  The final released sources will be tagged in the ``RELEASE_XY``
 209 directory as ``Final`` (c.f. :ref:`Tag the LLVM Final Release <tag>`).
 210
 211 The Release Manager may supply pre-packaged source tarballs for users.  This can
 212 be done with the following commands:
 213
 214 ::
 215
 216   $ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/rc1 llvm-X.Yrc1
 217   $ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/rc1 clang-X.Yrc1
 218   $ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/rc1 dragonegg-X.Yrc1
 219   $ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/rc1 llvm-test-X.Yrc1
 220
 221   $ tar -cvf - llvm-X.Yrc1        | gzip > llvm-X.Yrc1.src.tar.gz
 222   $ tar -cvf - clang-X.Yrc1       | gzip > clang-X.Yrc1.src.tar.gz
 223   $ tar -cvf - dragonegg-X.Yrc1   | gzip > dragonegg-X.Yrc1.src.tar.gz
 224   $ tar -cvf - llvm-test-X.Yrc1   | gzip > llvm-test-X.Yrc1.src.tar.gz
 225
 226 .. _release-build:
 227
 228 Building the Release
 229 --------------------
 230
 231 The builds of ``llvm``, ``clang``, and ``dragonegg`` *must* be free of
 232 errors and warnings in Debug, Release+Asserts, and Release builds.  If all
 233 builds are clean, then the release passes Build Qualification.
 234
 235 The ``make`` options for building the different modes:
 236
 237 +-----------------+---------------------------------------------+
 238 | Mode            | Options                                     |
 239 +=================+=============================================+
 240 | Debug           | ``ENABLE_OPTIMIZED=0``                      |
 241 +-----------------+---------------------------------------------+
 242 | Release+Asserts | ``ENABLE_OPTIMIZED=1``                      |
 243 +-----------------+---------------------------------------------+
 244 | Release         | ``ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` |
 245 +-----------------+---------------------------------------------+
 246
 247
 248 .. _build:
 249
 250 Build LLVM
 251 ^^^^^^^^^^
 252
 253 Build ``Debug``, ``Release+Asserts``, and ``Release`` versions
 254 of ``llvm`` on all supported platforms.  Directions to build ``llvm``
 255 are :ref:`here <getting_started>`.
 256
 257 .. _clangbin:
 258
 259 Build Clang Binary Distribution
 260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 261
 262 Creating the ``clang`` binary distribution (Debug/Release+Asserts/Release)
 263 requires performing the following steps for each supported platform:
 264
 265 #. Build clang according to the directions `here
 266    <http://clang.llvm.org/get_started.html>`__.
 267
 268 #. Build both a Debug and Release version of clang.  The binary will be the
 269    Release build.
 270
 271 #. Package ``clang`` (details to follow).
 272
 273 .. _target-build:
 274
 275 Target Specific Build Details
 276 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 277
 278 The table below specifies which compilers are used for each Arch/OS combination
 279 when qualifying the build of ``llvm``, ``clang``, and ``dragonegg``.
 280
 281 +--------------+---------------+----------------------+
 282 | Architecture | OS            | compiler             |
 283 +==============+===============+======================+
 284 | x86-32       | Mac OS 10.5   | gcc 4.0.1            |
 285 +--------------+---------------+----------------------+
 286 | x86-32       | Linux         | gcc 4.2.X, gcc 4.3.X |
 287 +--------------+---------------+----------------------+
 288 | x86-32       | FreeBSD       | gcc 4.2.X            |
 289 +--------------+---------------+----------------------+
 290 | x86-32       | mingw         | gcc 3.4.5            |
 291 +--------------+---------------+----------------------+
 292 | x86-64       | Mac OS 10.5   | gcc 4.0.1            |
 293 +--------------+---------------+----------------------+
 294 | x86-64       | Linux         | gcc 4.2.X, gcc 4.3.X |
 295 +--------------+---------------+----------------------+
 296 | x86-64       | FreeBSD       | gcc 4.2.X            |
 297 +--------------+---------------+----------------------+
 298
 299 .. _release-qualify:
 300
 301 Release Qualification Criteria
 302 ------------------------------
 303
 304 A release is qualified when it has no regressions from the previous release (or
 305 baseline).  Regressions are related to correctness first and performance second.
 306 (We may tolerate some minor performance regressions if they are deemed
 307 necessary for the general quality of the compiler.)
 308
 309 **Regressions are new failures in the set of tests that are used to qualify
 310 each product and only include things on the list.  Every release will have
 311 some bugs in it.  It is the reality of developing a complex piece of
 312 software.  We need a very concrete and definitive release criteria that
 313 ensures we have monotonically improving quality on some metric.  The metric we
 314 use is described below.  This doesn't mean that we don't care about other
 315 criteria, but these are the criteria which we found to be most important and
 316 which must be satisfied before a release can go out.**
 317
 318 .. _llvm-qualify:
 319
 320 Qualify LLVM
 321 ^^^^^^^^^^^^
 322
 323 LLVM is qualified when it has a clean test run without a front-end.  And it has
 324 no regressions when using either ``clang`` or ``dragonegg`` with the
 325 ``test-suite`` from the previous release.
 326
 327 .. _clang-qualify:
 328
 329 Qualify Clang
 330 ^^^^^^^^^^^^^
 331
 332 ``Clang`` is qualified when front-end specific tests in the ``llvm`` dejagnu
 333 test suite all pass, clang's own test suite passes cleanly, and there are no
 334 regressions in the ``test-suite``.
 335
 336 .. _target:
 337
 338 Specific Target Qualification Details
 339 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 340
 341 +--------------+-------------+----------------+-----------------------------+
 342 | Architecture | OS          | clang baseline | tests                       |
 343 +==============+=============+================+=============================+
 344 | x86-32       | Linux       | last release   | llvm dejagnu,               |
 345 |              |             |                | clang tests,                |
 346 |              |             |                | test-suite (including spec) |
 347 +--------------+-------------+----------------+-----------------------------+
 348 | x86-32       | FreeBSD     | last release   | llvm dejagnu,               |
 349 |              |             |                | clang tests,                |
 350 |              |             |                | test-suite                  |
 351 +--------------+-------------+----------------+-----------------------------+
 352 | x86-32       | mingw       | none           | QT                          |
 353 +--------------+-------------+----------------+-----------------------------+
 354 | x86-64       | Mac OS 10.X | last release   | llvm dejagnu,               |
 355 |              |             |                | clang tests,                |
 356 |              |             |                | test-suite (including spec) |
 357 +--------------+-------------+----------------+-----------------------------+
 358 | x86-64       | Linux       | last release   | llvm dejagnu,               |
 359 |              |             |                | clang tests,                |
 360 |              |             |                | test-suite (including spec) |
 361 +--------------+-------------+----------------+-----------------------------+
 362 | x86-64       | FreeBSD     | last release   | llvm dejagnu,               |
 363 |              |             |                | clang tests,                |
 364 |              |             |                | test-suite                  |
 365 +--------------+-------------+----------------+-----------------------------+
 366
 367 .. _commTest:
 368
 369 Community Testing
 370 -----------------
 371
 372 Once all testing has been completed and appropriate bugs filed, the release
 373 candidate tarballs are put on the website and the LLVM community is notified.
 374 Ask that all LLVM developers test the release in 2 ways:
 375
 376 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
 377    binary.  Build LLVM.  Run ``make check`` and the full LLVM test suite (``make
 378    TEST=nightly report``).
 379
 380 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources.  Compile
 381    everything.  Run ``make check`` and the full LLVM test suite (``make
 382    TEST=nightly report``).
 383
 384 Ask LLVM developers to submit the test suite report and ``make check`` results
 385 to the list.  Verify that there are no regressions from the previous release.
 386 The results are not used to qualify a release, but to spot other potential
 387 problems.  For unsupported targets, verify that ``make check`` is at least
 388 clean.
 389
 390 During the first round of testing, all regressions must be fixed before the
 391 second release candidate is tagged.
 392
 393 If this is the second round of testing, the testing is only to ensure that bug
 394 fixes previously merged in have not created new major problems. *This is not
 395 the time to solve additional and unrelated bugs!* If no patches are merged in,
 396 the release is determined to be ready and the release manager may move onto the
 397 next stage.
 398
 399 .. _release-patch:
 400
 401 Release Patch Rules
 402 -------------------
 403
 404 Below are the rules regarding patching the release branch:
 405
 406 #. Patches applied to the release branch may only be applied by the release
 407    manager.
 408
 409 #. During the first round of testing, patches that fix regressions or that are
 410    small and relatively risk free (verified by the appropriate code owner) are
 411    applied to the branch.  Code owners are asked to be very conservative in
 412    approving patches for the branch.  We reserve the right to reject any patch
 413    that does not fix a regression as previously defined.
 414
 415 #. During the remaining rounds of testing, only patches that fix critical
 416    regressions may be applied.
 417
 418 .. _release-final:
 419
 420 Release Final Tasks
 421 -------------------
 422
 423 The final stages of the release process involves tagging the "final" release
 424 branch, updating documentation that refers to the release, and updating the
 425 demo page.
 426
 427 .. _updocs:
 428
 429 Update Documentation
 430 ^^^^^^^^^^^^^^^^^^^^
 431
 432 Review the documentation and ensure that it is up to date.  The "Release Notes"
 433 must be updated to reflect new features, bug fixes, new known issues, and
 434 changes in the list of supported platforms.  The "Getting Started Guide" should
 435 be updated to reflect the new release version number tag available from
 436 Subversion and changes in basic system requirements.  Merge both changes from
 437 mainline into the release branch.
 438
 439 .. _tag:
 440
 441 Tag the LLVM Final Release
 442 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 443
 444 Tag the final release sources using the following procedure:
 445
 446 ::
 447
 448   $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
 449              https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/Final
 450
 451   $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
 452              https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/Final
 453
 454   $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
 455              https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/Final
 456
 457   $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
 458              https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/Final
 459
 460 .. _updemo:
 461
 462 Update the LLVM Demo Page
 463 -------------------------
 464
 465 The LLVM demo page must be updated to use the new release.  This consists of
 466 using the new ``clang`` binary and building LLVM.
 467
 468 .. _webupdates:
 469
 470 Update the LLVM Website
 471 ^^^^^^^^^^^^^^^^^^^^^^^
 472
 473 The website must be updated before the release announcement is sent out.  Here
 474 is what to do:
 475
 476 #. Check out the ``www`` module from Subversion.
 477
 478 #. Create a new subdirectory ``X.Y`` in the releases directory.
 479
 480 #. Commit the ``llvm``, ``test-suite``, ``clang`` source, ``clang binaries``,
 481    ``dragonegg`` source, and ``dragonegg`` binaries in this new directory.
 482
 483 #. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new
 484    directory.  The docs should be built with ``BUILD_FOR_WEBSITE=1``.
 485
 486 #. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use
 487    from previous release).
 488
 489 #. Update the ``releases/download.html`` file with the new release.
 490
 491 #. Update the ``releases/index.html`` with the new release and link to release
 492    documentation.
 493
 494 #. Finally, update the main page (``index.html`` and sidebar) to point to the
 495    new release and release announcement.  Make sure this all gets committed back
 496    into Subversion.
 497
 498 .. _announce:
 499
 500 Announce the Release
 501 ^^^^^^^^^^^^^^^^^^^^
 502
 503 Have Chris send out the release announcement when everything is finished.
 504