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