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
 242 Release Qualification Criteria
 243 ------------------------------
 244
 245 A release is qualified when it has no regressions from the previous release (or
 246 baseline).  Regressions are related to correctness first and performance second.
 247 (We may tolerate some minor performance regressions if they are deemed
 248 necessary for the general quality of the compiler.)
 249
 250 **Regressions are new failures in the set of tests that are used to qualify
 251 each product and only include things on the list.  Every release will have
 252 some bugs in it.  It is the reality of developing a complex piece of
 253 software.  We need a very concrete and definitive release criteria that
 254 ensures we have monotonically improving quality on some metric.  The metric we
 255 use is described below.  This doesn't mean that we don't care about other
 256 criteria, but these are the criteria which we found to be most important and
 257 which must be satisfied before a release can go out.**
 258
 259 Qualify LLVM
 260 ^^^^^^^^^^^^
 261
 262 LLVM is qualified when it has a clean test run without a front-end.  And it has
 263 no regressions when using either ``clang`` or ``dragonegg`` with the
 264 ``test-suite`` from the previous release.
 265
 266 Qualify Clang
 267 ^^^^^^^^^^^^^
 268
 269 ``Clang`` is qualified when front-end specific tests in the ``llvm`` regression
 270 test suite all pass, clang's own test suite passes cleanly, and there are no
 271 regressions in the ``test-suite``.
 272
 273 Specific Target Qualification Details
 274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 275
 276 +--------------+-------------+----------------+-----------------------------+
 277 | Architecture | OS          | clang baseline | tests                       |
 278 +==============+=============+================+=============================+
 279 | x86-32       | Linux       | last release   | llvm regression tests,      |
 280 |              |             |                | clang regression tests,     |
 281 |              |             |                | test-suite (including spec) |
 282 +--------------+-------------+----------------+-----------------------------+
 283 | x86-32       | FreeBSD     | last release   | llvm regression tests,      |
 284 |              |             |                | clang regression tests,     |
 285 |              |             |                | test-suite                  |
 286 +--------------+-------------+----------------+-----------------------------+
 287 | x86-32       | mingw       | none           | QT                          |
 288 +--------------+-------------+----------------+-----------------------------+
 289 | x86-64       | Mac OS 10.X | last release   | llvm regression tests,      |
 290 |              |             |                | clang regression tests,     |
 291 |              |             |                | test-suite (including spec) |
 292 +--------------+-------------+----------------+-----------------------------+
 293 | x86-64       | Linux       | last release   | llvm regression tests,      |
 294 |              |             |                | clang regression tests,     |
 295 |              |             |                | test-suite (including spec) |
 296 +--------------+-------------+----------------+-----------------------------+
 297 | x86-64       | FreeBSD     | last release   | llvm regression tests,      |
 298 |              |             |                | clang regression tests,     |
 299 |              |             |                | test-suite                  |
 300 +--------------+-------------+----------------+-----------------------------+
 301
 302 Community Testing
 303 -----------------
 304
 305 Once all testing has been completed and appropriate bugs filed, the release
 306 candidate tarballs are put on the website and the LLVM community is notified.
 307 Ask that all LLVM developers test the release in 2 ways:
 308
 309 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
 310    binary.  Build LLVM.  Run ``make check`` and the full LLVM test suite (``make
 311    TEST=nightly report``).
 312
 313 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources.  Compile
 314    everything.  Run ``make check`` and the full LLVM test suite (``make
 315    TEST=nightly report``).
 316
 317 Ask LLVM developers to submit the test suite report and ``make check`` results
 318 to the list.  Verify that there are no regressions from the previous release.
 319 The results are not used to qualify a release, but to spot other potential
 320 problems.  For unsupported targets, verify that ``make check`` is at least
 321 clean.
 322
 323 During the first round of testing, all regressions must be fixed before the
 324 second release candidate is tagged.
 325
 326 If this is the second round of testing, the testing is only to ensure that bug
 327 fixes previously merged in have not created new major problems. *This is not
 328 the time to solve additional and unrelated bugs!* If no patches are merged in,
 329 the release is determined to be ready and the release manager may move onto the
 330 next stage.
 331
 332 Release Patch Rules
 333 -------------------
 334
 335 Below are the rules regarding patching the release branch:
 336
 337 #. Patches applied to the release branch may only be applied by the release
 338    manager.
 339
 340 #. During the first round of testing, patches that fix regressions or that are
 341    small and relatively risk free (verified by the appropriate code owner) are
 342    applied to the branch.  Code owners are asked to be very conservative in
 343    approving patches for the branch.  We reserve the right to reject any patch
 344    that does not fix a regression as previously defined.
 345
 346 #. During the remaining rounds of testing, only patches that fix critical
 347    regressions may be applied.
 348
 349 Release Final Tasks
 350 -------------------
 351
 352 The final stages of the release process involves tagging the "final" release
 353 branch, updating documentation that refers to the release, and updating the
 354 demo page.
 355
 356 Update Documentation
 357 ^^^^^^^^^^^^^^^^^^^^
 358
 359 Review the documentation and ensure that it is up to date.  The "Release Notes"
 360 must be updated to reflect new features, bug fixes, new known issues, and
 361 changes in the list of supported platforms.  The "Getting Started Guide" should
 362 be updated to reflect the new release version number tag available from
 363 Subversion and changes in basic system requirements.  Merge both changes from
 364 mainline into the release branch.
 365
 366 .. _tag:
 367
 368 Tag the LLVM Final Release
 369 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 370
 371 Tag the final release sources using the following procedure:
 372
 373 ::
 374
 375   $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
 376              https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XY/Final
 377
 378   $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
 379              https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XY/Final
 380
 381   $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
 382              https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XY/Final
 383
 384   $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
 385              https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XY/Final
 386
 387 Update the LLVM Demo Page
 388 -------------------------
 389
 390 The LLVM demo page must be updated to use the new release.  This consists of
 391 using the new ``clang`` binary and building LLVM.
 392
 393 Update the LLVM Website
 394 ^^^^^^^^^^^^^^^^^^^^^^^
 395
 396 The website must be updated before the release announcement is sent out.  Here
 397 is what to do:
 398
 399 #. Check out the ``www`` module from Subversion.
 400
 401 #. Create a new subdirectory ``X.Y`` in the releases directory.
 402
 403 #. Commit the ``llvm``, ``test-suite``, ``clang`` source, ``clang binaries``,
 404    ``dragonegg`` source, and ``dragonegg`` binaries in this new directory.
 405
 406 #. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new
 407    directory.  The docs should be built with ``BUILD_FOR_WEBSITE=1``.
 408
 409 #. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use
 410    from previous release).
 411
 412 #. Update the ``releases/download.html`` file with the new release.
 413
 414 #. Update the ``releases/index.html`` with the new release and link to release
 415    documentation.
 416
 417 #. Finally, update the main page (``index.html`` and sidebar) to point to the
 418    new release and release announcement.  Make sure this all gets committed back
 419    into Subversion.
 420
 421 Announce the Release
 422 ^^^^^^^^^^^^^^^^^^^^
 423
 424 Have Chris send out the release announcement when everything is finished.
 425