419 lines · plain
1=================================2How To Release LLVM To The Public3=================================4 5Introduction6============7 8This document contains information about successfully releasing LLVM ---9including sub-projects: e.g., ``clang`` and ``compiler-rt`` --- to the public.10It is the Release Manager's responsibility to ensure that a high quality build11of LLVM is released.12 13If you're looking for the document on how to test the release candidates and14create the binary packages, please refer to the :doc:`ReleaseProcess` instead.15 16.. _timeline:17 18Release Timeline19================20 21LLVM is released on a time-based schedule --- with major releases roughly22every 6 months. In between major releases there may be dot releases.23The release manager will determine if and when to make a dot release based24on feedback from the community. Typically, dot releases should be made if25there are a large number of bug fixes in the stable branch or a critical bug26has been discovered that affects a large number of users.27 28Unless otherwise stated, dot releases will follow the same procedure as29major releases.30 31Annual Release Schedule32-----------------------33 34Here is the annual release schedule for LLVM. This is meant to be a35guide, and release managers are not required to follow this exactly.36Releases should be tagged on Tuesdays.37 38=============================== =========================39Release Approx. Date40=============================== =========================41*release branch: even releases* *2nd Tue in January*42*release branch: odd releases* *2nd Tue in July*43X.1.0-rc1 3 days after branch.44X.1.0-rc2 2 weeks after branch.45X.1.0-rc3 4 weeks after branch46**X.1.0-final** **6 weeks after branch**47**X.1.1** **8 weeks after branch**48**X.1.2** **10 weeks after branch**49**X.1.3** **12 weeks after branch**50**X.1.4** **14 weeks after branch**51**X.1.5** **16 weeks after branch**52**X.1.6** **18 weeks after branch**53**X.1.7** **20 weeks after branch**54**X.1.8** **22 weeks after branch**55**X.1.9** (If necessary) **24 weeks after branch**56**Next release branches** **~25 weeks after branch**57=============================== =========================58 59Release Process Summary60-----------------------61 62* Announce release schedule to the LLVM community and update the website. Do63 this at least 3 weeks before the -rc1 release.64 65* Create release branch and begin release process.66 67* Send out release candidate sources for first round of testing. Testing lasts68 6 weeks. During the first round of testing, any regressions found should be69 fixed. Patches are merged from mainline into the release branch. Also, all70 features need to be completed during this time. Any features not completed at71 the end of the first round of testing will be removed or disabled for the72 release.73 74* Generate and send out the second release candidate sources. Only *critical*75 bugs found during this testing phase will be fixed. Any bugs introduced by76 merged patches will be fixed. If so, a third round of testing is needed.77 78* The release notes are updated.79 80* Finally, release!81 82* Announce bug fix release schedule to the LLVM community and update the website.83 84* Do bug-fix releases every two weeks until X.1.5 or X.1.6 (if necessary).85 86Release Process87===============88 89.. contents::90 :local:91 92Release Administrative Tasks93----------------------------94 95This section describes a few administrative tasks that need to be done for the96release process to begin. Specifically, it involves:97 98* Updating version numbers,99 100* Creating the release branch, and101 102* Tagging release candidates for the release team to begin testing.103 104Create Release Branch and Update LLVM Version105^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^106 107Branch the Git trunk using the following procedure:108 109#. Remind developers that the release branching is imminent and to refrain from110 committing patches that might break the build, e.g., new features, large111 patches for works in progress, an overhaul of the type system, an exciting112 new TableGen feature, etc.113 114#. Verify that the current git trunk is in decent shape by115 examining nightly tester and buildbot results.116 117#. Bump the version in trunk to ``N.0.0git`` with the script in118 ``llvm/utils/release/bump-version.py``, and tag the commit with ``llvmorg-N-init``.119 If ``X`` is the version to be released, then ``N`` is ``X + 1``. ::120 121 $ git tag -sa llvmorg-N-init122 123#. Clear the release notes in trunk with the script in124 ``llvm/utils/release/clear-release-notes.py``.125 126#. Create the release branch from the last known good revision from before the127 version bump. The branch's name is ``release/X.x`` where ``X`` is the major version128 number and ``x`` is just the letter ``x``.129 130#. On the newly-created release branch, immediately bump the version131 to ``X.1.0git`` (where ``X`` is the major version of the branch.)132 133#. All tags and branches need to be created in both the ``llvm/llvm-project`` and134 ``llvm/llvm-test-suite`` repos.135 136Tagging the LLVM Release Candidates137^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^138 139Tag release candidates:140 141::142 143 $ git tag -sa llvmorg-X.Y.Z-rcN144 145The pre-packaged source tarballs will be automatically generated via the146`Release Sources147<https://github.com/llvm/llvm-project/actions/workflows/release-sources.yml>`_148workflow on GitHub. This workflow will create an artifact containing all the149release tarballs and the artifact attestation. The Release Manager should150download the artifact, verify the tarballs, sign them, and then upload them to151the release page.152 153::154 155 $ unzip artifact.zip156 $ gh auth login157 $ for f in *.xz; do gh attestation verify --owner llvm $f && gpg -b $f; done158 159Tarballs, release binaries, or any other release artifacts must be uploaded to160GitHub. This can be done using the ``github-upload-release.py`` script in ``utils/release``.161 162::163 164 $ github-upload-release.py upload --token <github-token> --release X.Y.Z-rcN --files <release_files>165 166 167Build The Binary Distribution168^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^169 170Creating the binary distribution requires following the instructions171:doc:`here <ReleaseProcess>`.172 173That process performs both Release+Asserts and Release builds but only packs174the Release build for upload. You should use the Release+Asserts sysroot,175normally under ``final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/``,176for test-suite and run-time benchmarks, to ensure nothing serious has177passed through the net. For compile-time benchmarks, use the Release version.178 179The minimum required version of the tools you'll need are :doc:`here <GettingStarted>`180 181Release Qualification Criteria182------------------------------183 184There are no official release qualification criteria.185The release manager determines when a release is ready. The release manager186should pay attention to the results of community testing, the number of outstanding187bugs, and the number of regressions when determining whether or not to make a188release.189 190The community values time based releases, so releases should not be delayed for191too long unless critical issues remain. In most cases, the only192kind of bugs that are critical enough to block a release would be a major regression193from a previous release.194 195Official Testing196----------------197 198A few developers in the community have dedicated time to validate the release199candidates and volunteered to be the official release testers for each200architecture.201 202These will be the ones testing, generating, and uploading the official binaries203to the server, and will be the minimum tests *necessary* for the release to204proceed.205 206This will obviously not cover all OSs and distributions, so additional community207validation is important. However, if community input is not received before the208release, all reported bugs will be deferred to the next stable release.209 210The official release managers are:211 212* Even releases: Tom Stellard (tstellar@redhat.com)213* Odd releases: Tobias Hieta (tobias@hieta.se)214 215The official release testers are volunteers from the community who have216consistently validated and released binaries for their targets/OSs. To contact217them, you should post on the `Discourse forums (Project218Infrastructure - Release Testers). <https://discourse.llvm.org/c/infrastructure/release-testers/66>`_219 220The official testers list is in the file ``RELEASE_TESTERS.TXT``221<https://github.com/llvm/llvm-project/blob/main/llvm/RELEASE_TESTERS.TXT>`_, in222the LLVM repository.223 224Community Testing225-----------------226 227Once all testing is complete and appropriate bugs are filed, the release228candidate tarballs are put on the website, and the LLVM community is notified.229 230We ask that all LLVM developers test the release in any the following ways:231 232#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``233 binary. Build LLVM. Run ``make check`` and the full LLVM test suite (``make234 TEST=nightly report``).235 236#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources. Compile237 everything. Run ``make check`` and the full LLVM test suite (``make238 TEST=nightly report``).239 240#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``241 binary. Build whole programs with it (ex. Chromium, Firefox, Apache) for242 your platform.243 244#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``245 binary. Build *your* programs with it and check for conformance and246 performance regressions.247 248#. Run the :doc:`release process <ReleaseProcess>`, if your platform is249 *different* than that which is officially supported, and report back errors250 only if they were not reported by the official release tester for that251 architecture.252 253We also ask that the OS distribution release managers test their packages with254the first candidate of every release and report any *new* errors in GitHub.255If the bug can be reproduced with an unpatched upstream version of the release256candidate (as opposed to the distribution's own build), the priority should be257release blocker.258 259During the first round of testing, all regressions must be fixed before the260second release candidate is tagged.261 262In the subsequent stages, the testing is only to ensure that bug263fixes previously merged in have not created new major problems. *This is not264the time to solve additional and unrelated bugs!* If no patches are merged in,265the release is determined to be ready and the release manager may move onto the266next stage.267 268Reporting Regressions269---------------------270 271Every regression found during the tests (as per the criteria above)272should be filled in a bug in GitHub and added to the release milestone.273 274If a bug can't be reproduced or stops being a blocker, it should be removed275from the Milestone. Debugging can continue, but on trunk.276 277Backport Requests278-----------------279 280Instructions for requesting a backport to a stable branch can be found281:ref:`here <backporting>`.282 283Triaging Bug Reports for Releases284---------------------------------285 286This section describes how to triage bug reports:287 288#. Search for bugs with a Release Milestone that have not been added to the289 "Release Status" github project:290 291 https://github.com/llvm/llvm-project/issues?q=is%3Aissue+milestone%3A%22LLVM+14.0.5+Release%22+no%3Aproject+292 293 Replace 14.0.5 in this query with the version from the Release Milestone being294 targeted.295 296 Add these bugs to the "Release Status" project.297 298#. Navigate to the `Release Status project <https://github.com/orgs/llvm/projects/3>`_299 to see the list of bugs that are being considered for the release.300 301#. Review each bug and first check if it has been fixed in main. If it has, update302 its status to "Needs Pull Request" and create a pull request for the fix303 using the ``/cherry-pick`` or ``/branch`` comments if this has not been done already.304 305#. If a bug has been fixed and has a pull request created for backporting it,306 then update its status to "Needs Review" and notify a knowledgeable307 reviewer. Usually you will want to notify the person who approved the308 patch, but you may use your best judgement on who a good reviewer would be.309 Once you have identified the reviewer(s), assign the issue to them and310 mention them (i.e., ``@username``) in a comment and ask them if the patch is safe311 to backport. You should also review the bug yourself to ensure that it312 meets the requirements for committing to the release branch.313 314#. Once a bug has been reviewed, update the status to "Needs Merge". Check the315 pull request associated with the issue. If all the tests pass, then the pull316 request can be merged. If not, then add a comment on the issue asking317 someone to take a look at the failures.318 319 320Release Patch Rules321-------------------322 323Below are the rules regarding patching the release branch:324 325#. Patches applied to the release branch may only be applied by the release326 manager, the official release testers, or the maintainers with approval from327 the release manager.328 329#. Release managers are encouraged, but not required, to get approval from a330 maintainer before approving patches. If there are no reachable maintainers,331 then release managers can ask approval from patch reviewers or other332 developers active in that area.333 334#. *Before RC1* Patches should be limited to bug fixes, important optimization335 improvements, or completion of features that were started before the branch336 was created. As with all phases, release managers and maintainers can reject337 patches that are deemed too invasive.338 339#. *Before RC2/RC3* Patches should be limited to bug fixes or backend-specific340 improvements that are determined to be very safe.341 342#. *Before Final Major Release* Patches should be limited to critical343 bugs or regressions.344 345#. *Bug fix releases* Patches should be limited to bug fixes or very safe346 and critical performance improvements. Patches must maintain both API and347 ABI compatibility with the X.1.0 release.348 349Release Final Tasks350-------------------351 352The final stages of the release process involve tagging the "final" release353branch, updating documentation that refers to the release, and updating the354demo page.355 356Update Documentation357^^^^^^^^^^^^^^^^^^^^358 359Review the documentation in the release branch and ensure that it is up360to date. The "Release Notes" must be updated to reflect new features, bug361fixes, new known issues, and changes in the list of supported platforms.362The :doc:`GettingStarted` page should be updated to reflect the new release363version number tag and changes in basic system requirements.364 365.. _tag:366 367Tag the LLVM Final Release368^^^^^^^^^^^^^^^^^^^^^^^^^^369 370Tag the final release sources:371 372::373 374 $ git tag -sa llvmorg-X.Y.Z375 $ git push https://github.com/llvm/llvm-project.git llvmorg-X.Y.Z376 377Update the LLVM Website378^^^^^^^^^^^^^^^^^^^^^^^379 380The website must be updated before the release announcement is sent out. Here381is what to do:382 383#. Check out the `www-releases <https://github.com/llvm/www-releases>`_ repo384 from GitHub.385 386#. Create a new sub-directory ``X.Y.Z`` in the releases directory.387 388#. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new389 directory.390 391#. Update the ``releases/download.html`` file with links to the release392 binaries on GitHub.393 394#. Update the ``releases/index.html`` with the new release and link to release395 documentation.396 397#. After you push the changes to the ``www-releases`` repo, someone with admin398 access must log in to ``prereleases-origin.llvm.org`` and manually pull the new399 changes into ``/data/www-releases/``. This is where the website is served from.400 401#. Finally, check out the ``llvm-www`` repo and update the main page402 (``index.html`` and sidebar) to point to the new release and release403 announcement.404 405Announce the Release406^^^^^^^^^^^^^^^^^^^^407 408Create a new post in the `Announce Category <https://discourse.llvm.org/c/announce>`_409once all the release tasks are complete. For X.1.0 releases, make sure to include a410link to the release notes in the post. For X.1.1+ releases, generate a changelog411using this command and add it to the post.412 413::414 415 $ git log --format="- %aN: [%s (%h)](https://github.com/llvm/llvm-project/commit/%H)" llvmorg-X.1.N-1..llvmorg-X.1.N416 417Once the release has been announced, add a link to the announcement on the llvm418homepage (from the ``llvm-www`` repo) in the "Release Emails" section.419