[llvm] 25f05c0 - [llvm][release] On release page, explain package types and verification (#138144)

[via llvm-commits]

Author: David Spickett
Date: 2025-07-04T09:02:38+01:00
New Revision: 25f05c02afb99c3af483bfb8bc3abac54f4cabc3

URL: https://github.com/llvm/llvm-project/commit/25f05c02afb99c3af483bfb8bc3abac54f4cabc3
DIFF: https://github.com/llvm/llvm-project/commit/25f05c02afb99c3af483bfb8bc3abac54f4cabc3.diff

LOG: [llvm][release] On release page, explain package types and verification (#138144)

Background:
https://discourse.llvm.org/t/rfc-explaining-release-package-types-and-purposes/85985

So that users can understand which they should use, particularly for
Windows. The original text about community builds is kept, after
explaining the main release package formats.

In addition, explain how to use gpg or gh to verify the packages.

Added: 
    

Modified: 
    llvm/utils/release/github-upload-release.py

Removed: 
    


################################################################################
diff  --git a/llvm/utils/release/github-upload-release.py b/llvm/utils/release/github-upload-release.py
index 8343dee937f78..e9591b00e2b5a 100755
--- a/llvm/utils/release/github-upload-release.py
+++ b/llvm/utils/release/github-upload-release.py
@@ -42,18 +42,45 @@ def create_release(repo, release, tag=None, name=None, message=None):
         name = "LLVM {}".format(release)
 
     if not message:
+        # Note that these lines are not length limited because if we do so, GitHub
+        # assumes that should be how it is laid out on the page. We want GitHub to
+        # do the reflowing for us instead.
         message = dedent(
             """\
-            LLVM {} Release
+LLVM {release} Release
 
-            # A note on binaries
+## Package Types
 
-            Volunteers make binaries for the LLVM project, which will be uploaded
-            when they have had time to test and build these binaries. They might
-            not be available directly or not at all for each release. We suggest
-            you use the binaries from your distribution or build your own if you
-            rely on a specific platform or configuration."""
-        ).format(release)
+Each platform has one binary release package. The file name starts with either `LLVM-` or `clang+llvm-` and ends with the platform's name. For example, `LLVM-{release}-Linux-ARM64.tar.xz` contains LLVM binaries for Arm64 Linux.
+
+Except for Windows. Where `LLVM-*.exe` is an installer intended for using LLVM as a toolchain and `clang+llvm-` contains the contents of the installer, plus libraries and tools not normally used in a toolchain. You most likely want the `LLVM-` installer, unless you are developing software which itself uses LLVM, in which case choose `clang+llvm-`.
+
+If you do not find a release package for your platform, you may be able to find a community built package on the LLVM Discourse forum thread for this release. Remember that these are built by volunteers and may not always be available.
+
+If you rely on a platform or configuration that is not one of the defaults, we suggest you use the binaries that your platform provides, or build your own release packages.
+
+In addition, source archives are available:
+* `<sub-project>-{release}.src.tar.xz` are archives of the sources of specific sub-projects of `llvm-project` (except for `test-suite` which is an archive of the [LLVM Test Suite](https://github.com/llvm/llvm-test-suite)).
+* To get all the `llvm-project` source code for this release, choose `llvm-project-{release}.src.tar.xz`.
+
+## Verifying Packages
+
+All packages come with a matching `.sig` or `.jsonl` file. You should use these to verify the integrity of the packages.
+
+If it has a `.sig` file, it should have been signed by the release managers using GPG. Download the keys from the [LLVM website](https://releases.llvm.org/release-keys.asc), import them into your keyring and use them to verify the file:
+```
+$ gpg --import release-keys.asc
+$ gpg --verify <package file name>.sig <package file name>
+```
+
+If it has a `.jsonl` file, use [gh](https://cli.github.com/manual/gh_attestation_verify) to verify the package:
+```
+gh attestation verify --repo llvm/llvm-project <package file name>
+(if you are able to connect to GitHub)
+gh attestation verify --repo llvm/llvm-project <package file name> --bundle <package file name>.jsonl
+(using attestation file on disk)
+```"""
+        ).format(release=release)
 
     prerelease = True if "rc" in release else False