docs/HowToReleaseLLVM.rst

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