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