From a957a27451e94c4aafad6a58c740b080774d71c1 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:48:34 +0000
Subject: [PATCH 1/7] Prepare 1.13.0 release documentation and migration notes

---
 .github/workflows/release_notes_template.txt | 26 ++++----
 CHANGELOG.md                                 | 64 ++++++++++++++++++++
 README.md                                    | 38 +++++++++---
 3 files changed, 107 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt
index 5b858b19..7fd2115d 100644
--- a/.github/workflows/release_notes_template.txt
+++ b/.github/workflows/release_notes_template.txt
@@ -1,5 +1,12 @@
 Minimum bazel version: **7.0.0**
 
+See the [changelog](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/CHANGELOG.md)
+for changes and migration notes for this release. Upgrading from 1.12.x to
+1.13.0 changes prerelease selectors: to keep prereleases eligible, requirements
+naming an RC now also need `llvm_version_allow_prereleases = True`, or
+`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins,
+including RC pins, are unchanged.
+
 If you're using `bzlmod`, add the following to `MODULE.bazel`:
 
 ```starlark
@@ -8,11 +15,7 @@ bazel_dep(name = "toolchains_llvm", version = "{version}")
 # Configure and register the toolchain.
 llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm")
 llvm.toolchain(
-    llvm_version = "23.1.2",
-    linker = {
-        "darwin-aarch64": "auto",
-        "darwin-x86_64": "auto",
-    },
+    llvm_version = "23.1.4",
 )
 
 use_repo(llvm, "llvm_toolchain")
@@ -21,6 +24,11 @@ use_repo(llvm, "llvm_toolchain")
 register_toolchains("@llvm_toolchain//:all")
 ```
 
+These examples use the linker bundled with LLVM 23.1.4; its macOS linker does
+not require the LLVM 23.1.0–23.1.2 SDK/TAPI workaround. LLVM 23.1.4 has no macOS
+x86_64 archive; Intel Mac users must select another available LLVM version
+through `llvm_version` or `llvm_versions`.
+
 To directly use a commit from GitHub, add this block and replace commit with the commit you want.
 ```starlark
 git_override(
@@ -55,7 +63,7 @@ load("@rules_cc//cc:extensions.bzl", "compatibility_proxy_repo")
 
 # If you see an error:
 #   ERROR: Cycle caused by autoloads, failed to load .bzl file '@@cc_compatibility_proxy//:symbols.bzl'.
-# then you might need to add the following to your .bzelrc:
+# then you might need to add the following to your .bazelrc:
 #   common --repositories_without_autoloads=cc_compatibility_proxy
 compatibility_proxy_repo()
 
@@ -63,11 +71,7 @@ load("@toolchains_llvm//toolchain:rules.bzl", "llvm_toolchain")
 
 llvm_toolchain(
     name = "llvm_toolchain",
-    llvm_version = "23.1.2",
-    linker = {
-        "darwin-aarch64": "auto",
-        "darwin-x86_64": "auto",
-    },
+    llvm_version = "23.1.4",
 )
 
 load("@llvm_toolchain//:toolchains.bzl", "llvm_register_toolchains")
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 75509274..20cecf47 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,70 @@ exhaustive list of fixes, dependency updates, or newly catalogued LLVM archives.
 See the [GitHub releases](https://github.com/bazel-contrib/toolchains_llvm/releases)
 for release artifacts and the [README](README.md) for configuration and requirements.
 
+## 1.13.0
+
+### Migration required for prerelease selectors
+
+- `first` and `latest` no longer enable prereleases implicitly when a
+  requirement names an RC. Set `llvm_version_allow_prereleases = True` for LLVM,
+  or `linker_version_allow_prereleases = True` for catalogued linkers, to admit
+  matching prereleases. Both options default to `False` and are independent.
+  Exact pins, including RC pins, are unchanged.
+- Enabling either option admits every prerelease satisfying the requirements,
+  rather than only prereleases with a release tuple named in the requirement.
+  Use an upper bound when following RCs for one release, for example
+  `llvm_version = "latest:>=23.1.0-rc1,<23.1.0"` together with
+  `llvm_version_allow_prereleases = True`.
+- Version comparisons now use bzl's SemVer mode. Alphanumeric prerelease
+  identifiers compare lexically: `23.1.0-rc10` sorts before `23.1.0-rc2`.
+  Use an exact pin when the upstream RC numbering does not follow that ordering.
+
+### Version selection
+
+- Shared expression-based LLVM and linker version selectors, including
+  `major`, `minor`, and `patch` constants, function expressions, wildcards,
+  and compatible-release comparisons. Candidates must have an artifact for
+  the execution platform before version selection.
+- Environment-derived linker versions through `getenv(NAME,fallback)`, matching
+  LLVM version selection.
+- Independent prerelease policies in feature overrides; linker-only policy
+  changes can reuse the base LLVM archive.
+
+### Dependencies and publishing
+
+- WORKSPACE dependencies: `rules_cc` 0.2.27, `apple_support` 2.11.0, and
+  `bazel_features` 1.54.1.
+- Test dependencies, including `rules_python` 2.4.6, `rules_go` 0.65.0,
+  `rules_foreign_cc` 0.17.0, `rules_rust` 0.75.0, and BoringSSL 0.20261020.0.
+- BCR publishing workflow to `publish-to-bcr` 1.6.0.
+
+## 1.12.0
+
+- Add checksum-pinned LLVM 23.1.4 archives for Linux ARM64/x86_64, macOS ARM64,
+  and Windows ARM64/x86_64. Both xz and zstd metadata are retained; automatic
+  selection continues to use xz. Existing LLVM and mold entries are preserved.
+- Fix remote execution of dynamically linked LLVM tools: wrappers execute
+  auxiliary tools from their original distribution paths, preserving relative
+  shared-library lookup. Downloaded distributions supply the relevant LLVM,
+  Clang, and libc++ shared libraries as tool inputs.
+- Explicit `archive_flags`, `link_libs`, optimization/debug/fastbuild flags,
+  coverage flags, and `unfiltered_compile_flags` replace their corresponding
+  defaults. Use the corresponding `extra_*` attribute where available for
+  additive behavior. `compile_flags`, `cxx_flags`, and `link_flags` still append
+  to their computed defaults.
+- Use `-fstack-protector-strong` instead of `-fstack-protector` by default.
+- Report Linux `target_libc` as `glibc` instead of `glibc_unknown`.
+- Upgrade `mboworks_bzl` to 0.8.0 and the WORKSPACE test dependency Google
+  Benchmark to 1.10.0. The new selector expressions and explicit prerelease
+  controls are introduced in 1.13.0, not in this dependency upgrade.
+
+## 1.11.3
+
+- Recognize LLVM 23.1.3's bundled macOS linker fix. The SDK/TAPI warning now
+  applies only to LLVM 23.1.0 through 23.1.2, not all LLVM 23 releases.
+- Update WORKSPACE dependencies to `apple_support` 2.10.1 and `bazel_features`
+  1.52.0, and test dependencies to `rules_python` 2.4.2 and `rules_go` 0.64.2.
+
 ## 1.11.2
 
 - Honor the empty-key fallback in `conly_flags` for every target, matching the
diff --git a/README.md b/README.md
index 322d210d..1a96f6a2 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ for how to get started, and the [changelog](CHANGELOG.md) for feature availabili
 
 NOTE: For releases prior to 0.10.1, please also see [these notes](REPO_RENAME.md).
 
-<!-- Release Notes template is at .github/workflows/release_prep.sh -->
+<!-- Release notes template: .github/workflows/release_notes_template.txt -->
 
 ## Basic Usage
 
@@ -18,6 +18,16 @@ below for more options.
 See in-code documentation in [rules.bzl](toolchain/rules.bzl) for available
 attributes to `llvm_toolchain`.
 
+### Upgrading to 1.13.0
+
+Version selection has an intentional compatibility change: `first` / `latest`
+requirements that mention an RC no longer enable prereleases implicitly. To keep
+prereleases eligible, add `llvm_version_allow_prereleases = True` for LLVM, or
+`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins
+(including RC pins) are unchanged. See the [migration notes](CHANGELOG.md#1130)
+and [requirements examples](#requirements) before upgrading configurations
+that select prereleases.
+
 ## Advanced Usage
 
 ### Per host architecture LLVM version
@@ -236,6 +246,11 @@ for how CC toolchains work in general.
 
 ### Requirements
 
+Expression-based selectors and the independent prerelease controls below are
+available starting with toolchains_llvm 1.13.0. Basic `first` / `latest`
+comparisons were introduced in 1.6.0; see the [changelog](CHANGELOG.md) for
+earlier feature availability.
+
 Version requirements let projects bind automatic LLVM upgrades to deliberate `toolchains_llvm`
 release upgrades. A `toolchains_llvm` release can add new LLVM release identifiers to its
 checksummed catalogue. Upgrading the pinned module then makes those releases eligible without a
@@ -270,7 +285,7 @@ linker versions, and lets one configuration accommodate hosts whose available ar
 Conditions are comma-separated and combined with AND. toolchains_llvm supplies `major`, `minor`,
 and `patch` as numeric release-component constants, so `latest:major==23,minor>=2` stays within
 LLVM 23 and requires a minor version of at least 2. Comparisons and function expressions use
-[mboworks_bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#semver).
+[mboworks_bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#semver).
 
 <!-- prettier-ignore -->
 | Selector                    | Selection policy                               |
@@ -281,9 +296,9 @@ LLVM 23 and requires a minor version of at least 2. Comparisons and function exp
 | `first:>=22,<23`            | Oldest stable LLVM 22 release for the host     |
 
 For all comparison operators, wildcard matching and compatible-release boundaries, see
-[Compatible and matching requirements](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#compatible-and-matching-requirements).
+[Compatible and matching requirements](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#compatible-and-matching-requirements).
 Function clauses such as `major()==23` and more advanced inspection are documented under
-[Requirement expressions and constants](https://mboworks.github.io/bzl/site/tag/0.7.0/docs/versions.html#requirement-expressions-and-constants).
+[Requirement expressions and constants](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#requirement-expressions-and-constants).
 
 `llvm_version_allow_prereleases` and `linker_version_allow_prereleases` each
 default to `False`. They independently control bare and constrained
@@ -302,6 +317,10 @@ llvm.toolchain(
 
 This selects the newest matching release candidate available for the execution
 host. With `llvm_version_allow_prereleases = False`, that RC-only range has no matching release.
+Enabling prereleases admits all versions satisfying the requirement, so retain
+the upper bound when following RCs for one release. SemVer compares alphanumeric
+prerelease identifiers lexically: `23.1.0-rc10` sorts before `23.1.0-rc2`.
+Use an exact pin when the upstream RC numbering does not follow that ordering.
 With the option enabled, expressions such as `is_prerelease()==True` can further
 restrict selection to prereleases; `is_prerelease()==False` can restrict a
 particular selector to stable releases.
@@ -334,12 +353,11 @@ reuse the base LLVM archive.
 It is further possible to provide the version or requirement from an environment
 variable with a fallback version or requirement. This works for both LLVM and
 linker versions, for example `linker_version = "getenv(MOLD_VERSION,latest:major==3)"`
-with `--repo_env=MOLD_VERSION=3.0.0`. In this case it is important to
-also use the bazel flag `--repo_env=LLVM_VERSION=version_or_requirement`. It is
-important to use both correctly because otherwise the resulting builds are not
-reproducible. The main purpose of using an environment variable to encode the
-version for integration or batch testing on multiple platforms where multiple
-LLVM versions should be tested.
+with `--repo_env=MOLD_VERSION=3.0.0`. Set the same variable named in `getenv`
+through Bazel's `--repo_env=NAME=value`; for LLVM examples below, use
+`--repo_env=LLVM_VERSION=version_or_requirement`. This makes the selected input
+explicit. Environment-based selection is useful for integration or batch
+testing across multiple LLVM or linker versions.
 
 - `getenv(ENVIRONMENT_VARIABLE_NAME,fallback)`
 

From 6b90804c1c2381d87b0343034829a38cbdf7d0e2 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:56:13 +0000
Subject: [PATCH 2/7] Clarify the explicit prerelease opt-in before 1.13.0

---
 .github/workflows/release_notes_template.txt | 11 ++++++-----
 CHANGELOG.md                                 | 13 ++++++++-----
 README.md                                    | 13 +++++++------
 3 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt
index 7fd2115d..effebabd 100644
--- a/.github/workflows/release_notes_template.txt
+++ b/.github/workflows/release_notes_template.txt
@@ -1,11 +1,12 @@
 Minimum bazel version: **7.0.0**
 
 See the [changelog](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/CHANGELOG.md)
-for changes and migration notes for this release. Upgrading from 1.12.x to
-1.13.0 changes prerelease selectors: to keep prereleases eligible, requirements
-naming an RC now also need `llvm_version_allow_prereleases = True`, or
-`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins,
-including RC pins, are unchanged.
+for changes and migration notes for this release. In 1.12.x, `first` / `latest`
+selectors admitted prereleases only when a requirement explicitly specified a
+prerelease version, and only for that same major/minor/patch release. In 1.13.0,
+that explicit requirement is no longer sufficient: also set
+`llvm_version_allow_prereleases = True`, or `linker_version_allow_prereleases = True`
+for catalogued linkers. Exact pins, including RC pins, are unchanged.
 
 If you're using `bzlmod`, add the following to `MODULE.bazel`:
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20cecf47..b616227e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,11 +11,14 @@ for release artifacts and the [README](README.md) for configuration and requirem
 
 ### Migration required for prerelease selectors
 
-- `first` and `latest` no longer enable prereleases implicitly when a
-  requirement names an RC. Set `llvm_version_allow_prereleases = True` for LLVM,
-  or `linker_version_allow_prereleases = True` for catalogued linkers, to admit
-  matching prereleases. Both options default to `False` and are independent.
-  Exact pins, including RC pins, are unchanged.
+- Previously, `first` / `latest` selectors admitted prereleases only when a
+  requirement explicitly specified a prerelease version, and only for that
+  same major/minor/patch release. Starting with 1.13.0, explicitly specifying
+  an RC in a requirement is no longer sufficient: also set
+  `llvm_version_allow_prereleases = True` for LLVM, or
+  `linker_version_allow_prereleases = True` for catalogued linkers. Both options
+  default to `False` and are independent. Exact pins, including RC pins, are
+  unchanged.
 - Enabling either option admits every prerelease satisfying the requirements,
   rather than only prereleases with a release tuple named in the requirement.
   Use an upper bound when following RCs for one release, for example
diff --git a/README.md b/README.md
index 1a96f6a2..d1dfb61b 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,10 @@ attributes to `llvm_toolchain`.
 
 ### Upgrading to 1.13.0
 
-Version selection has an intentional compatibility change: `first` / `latest`
-requirements that mention an RC no longer enable prereleases implicitly. To keep
-prereleases eligible, add `llvm_version_allow_prereleases = True` for LLVM, or
+Previously, `first` / `latest` selectors admitted prereleases only when a
+requirement explicitly specified a prerelease version, and only for that same
+major/minor/patch release. In 1.13.0, that explicit requirement is no longer
+sufficient: also set `llvm_version_allow_prereleases = True` for LLVM, or
 `linker_version_allow_prereleases = True` for catalogued linkers. Exact pins
 (including RC pins) are unchanged. See the [migration notes](CHANGELOG.md#1130)
 and [requirements examples](#requirements) before upgrading configurations
@@ -303,9 +304,9 @@ Function clauses such as `major()==23` and more advanced inspection are document
 `llvm_version_allow_prereleases` and `linker_version_allow_prereleases` each
 default to `False`. They independently control bare and constrained
 `first`/`latest` selectors for LLVM and catalogued linkers, respectively. Requirements always
-apply; enabling prereleases does not bypass ranges or host availability. Naming
-an RC in a requirement does not implicitly enable prereleases. Exact version pins
-are unaffected.
+apply; enabling prereleases does not bypass ranges or host availability.
+Explicitly specifying an RC version in a requirement does not by itself enable
+prereleases. Exact version pins are unaffected.
 
 ```starlark
 llvm.toolchain(

From 89033c265077b8653fea5c4029024693f64bb1f1 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:01:41 +0000
Subject: [PATCH 3/7] Clarify prerelease eligibility and SemVer RC ordering

---
 .github/workflows/release_notes_template.txt |  4 ++-
 CHANGELOG.md                                 | 21 +++++++-----
 README.md                                    | 36 ++++++++++++--------
 3 files changed, 37 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt
index effebabd..e1706e6f 100644
--- a/.github/workflows/release_notes_template.txt
+++ b/.github/workflows/release_notes_template.txt
@@ -6,7 +6,9 @@ selectors admitted prereleases only when a requirement explicitly specified a
 prerelease version, and only for that same major/minor/patch release. In 1.13.0,
 that explicit requirement is no longer sufficient: also set
 `llvm_version_allow_prereleases = True`, or `linker_version_allow_prereleases = True`
-for catalogued linkers. Exact pins, including RC pins, are unchanged.
+for catalogued linkers. These flags separate prerelease eligibility from version
+constraints, which no longer need to name an RC. Exact pins, including RC pins,
+are unchanged.
 
 If you're using `bzlmod`, add the following to `MODULE.bazel`:
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b616227e..cc068929 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,14 +19,19 @@ for release artifacts and the [README](README.md) for configuration and requirem
   `linker_version_allow_prereleases = True` for catalogued linkers. Both options
   default to `False` and are independent. Exact pins, including RC pins, are
   unchanged.
-- Enabling either option admits every prerelease satisfying the requirements,
-  rather than only prereleases with a release tuple named in the requirement.
-  Use an upper bound when following RCs for one release, for example
-  `llvm_version = "latest:>=23.1.0-rc1,<23.1.0"` together with
-  `llvm_version_allow_prereleases = True`.
-- Version comparisons now use bzl's SemVer mode. Alphanumeric prerelease
-  identifiers compare lexically: `23.1.0-rc10` sorts before `23.1.0-rc2`.
-  Use an exact pin when the upstream RC numbering does not follow that ordering.
+- Prerelease eligibility and version constraints are now separate: enable
+  prereleases with the corresponding flag, then use ordinary constraints
+  without naming a particular RC. For example,
+  `llvm_version = "latest:>23.0,<23.1"` together with
+  `llvm_version_allow_prereleases = True` admits LLVM 23.1.0 RCs but excludes
+  the final 23.1.0 release. The flag admits all prereleases within the range,
+  rather than only those with a release tuple explicitly named in it.
+- Version comparisons now use bzl's SemVer mode. Under
+  [SemVer's prerelease ordering rules](https://semver.org/#spec-item-11),
+  dot-separated numeric identifiers compare numerically (`rc.2 < rc.10`),
+  but identifiers containing letters compare lexically (`rc10 < rc2`).
+  Thus `23.1.0-rc10` sorts before `23.1.0-rc2`; use an exact pin if that
+  differs from the intended upstream RC order.
 
 ### Version selection
 
diff --git a/README.md b/README.md
index d1dfb61b..71316946 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,9 @@ requirement explicitly specified a prerelease version, and only for that same
 major/minor/patch release. In 1.13.0, that explicit requirement is no longer
 sufficient: also set `llvm_version_allow_prereleases = True` for LLVM, or
 `linker_version_allow_prereleases = True` for catalogued linkers. Exact pins
-(including RC pins) are unchanged. See the [migration notes](CHANGELOG.md#1130)
+(including RC pins) are unchanged. The flag now controls prerelease eligibility
+separately from the constraints, which no longer need to name an RC.
+See the [migration notes](CHANGELOG.md#1130)
 and [requirements examples](#requirements) before upgrading configurations
 that select prereleases.
 
@@ -303,28 +305,32 @@ Function clauses such as `major()==23` and more advanced inspection are document
 
 `llvm_version_allow_prereleases` and `linker_version_allow_prereleases` each
 default to `False`. They independently control bare and constrained
-`first`/`latest` selectors for LLVM and catalogued linkers, respectively. Requirements always
-apply; enabling prereleases does not bypass ranges or host availability.
-Explicitly specifying an RC version in a requirement does not by itself enable
-prereleases. Exact version pins are unaffected.
+`first`/`latest` selectors for LLVM and catalogued linkers, respectively.
+The flag controls whether prereleases are eligible; the requirements control
+which versions qualify. Constraints no longer need to name an RC, and naming
+one does not by itself enable prereleases. Requirements and host availability
+always apply. Exact version pins are unaffected.
 
 ```starlark
 llvm.toolchain(
     name = "llvm_rc",
-    llvm_version = "latest:>=23.1.0-rc1,<23.1.0",
+    llvm_version = "latest:>23.0,<23.1",
     llvm_version_allow_prereleases = True,
 )
 ```
 
-This selects the newest matching release candidate available for the execution
-host. With `llvm_version_allow_prereleases = False`, that RC-only range has no matching release.
-Enabling prereleases admits all versions satisfying the requirement, so retain
-the upper bound when following RCs for one release. SemVer compares alphanumeric
-prerelease identifiers lexically: `23.1.0-rc10` sorts before `23.1.0-rc2`.
-Use an exact pin when the upstream RC numbering does not follow that ordering.
-With the option enabled, expressions such as `is_prerelease()==True` can further
-restrict selection to prereleases; `is_prerelease()==False` can restrict a
-particular selector to stable releases.
+This admits LLVM 23.1.0 release candidates without naming a particular RC and
+excludes the final 23.1.0 release (`23.1` means `23.1.0`). It selects the newest
+matching version available for the execution host. Stable releases within
+the range remain eligible; append `,is_prerelease()==True` if selection
+must be strictly prerelease-only. With the flag set to `False`, only matching
+stable releases are eligible. Conversely, `is_prerelease()==False` restricts a
+particular selector to stable releases even when the flag is enabled.
+
+[SemVer compares dot-separated prerelease identifiers](https://semver.org/#spec-item-11)
+numerically when they contain only digits (`rc.2 < rc.10`), but lexically when
+they contain letters (`rc10 < rc2`). Consequently, `23.1.0-rc10` sorts before
+`23.1.0-rc2`. Use an exact pin if that differs from the intended upstream RC order.
 
 Linker selectors use the same bzl SemVer comparisons, requirement expressions,
 projection constants, and first/latest selection as LLVM. For example:

From e9d4764549d73c035c3aac4441d7ad3a7301c107 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:03:54 +0000
Subject: [PATCH 4/7] Document LLVM RC spelling and mixed-format ordering

---
 CHANGELOG.md |  6 ++++--
 README.md    | 12 ++++++++++--
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cc068929..c51c317b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,8 +30,10 @@ for release artifacts and the [README](README.md) for configuration and requirem
   [SemVer's prerelease ordering rules](https://semver.org/#spec-item-11),
   dot-separated numeric identifiers compare numerically (`rc.2 < rc.10`),
   but identifiers containing letters compare lexically (`rc10 < rc2`).
-  Thus `23.1.0-rc10` sorts before `23.1.0-rc2`; use an exact pin if that
-  differs from the intended upstream RC order.
+  LLVM currently uses undotted RC identifiers, such as `23.1.0-rc3`.
+  A hypothetical `23.1.0-rc10` would therefore sort before `23.1.0-rc2`;
+  mixing forms also gives `23.1.0-rc.10 < 23.1.0-rc9`. Use an exact pin
+  if that differs from the intended upstream RC order.
 
 ### Version selection
 
diff --git a/README.md b/README.md
index 71316946..74bee482 100644
--- a/README.md
+++ b/README.md
@@ -329,8 +329,16 @@ particular selector to stable releases even when the flag is enabled.
 
 [SemVer compares dot-separated prerelease identifiers](https://semver.org/#spec-item-11)
 numerically when they contain only digits (`rc.2 < rc.10`), but lexically when
-they contain letters (`rc10 < rc2`). Consequently, `23.1.0-rc10` sorts before
-`23.1.0-rc2`. Use an exact pin if that differs from the intended upstream RC order.
+they contain letters (`rc10 < rc2`). LLVM currently uses the undotted form,
+for example [23.1.0-rc3](https://github.com/llvm/llvm-project/releases/tag/llvmorg-23.1.0-rc3),
+not `23.1.0-rc.3`. Between matching `23.1.0-rc2` and hypothetical `23.1.0-rc10`,
+`latest` would choose `rc2`. If LLVM instead used `23.1.0-rc.2` and
+`23.1.0-rc.10`, `latest` would choose `rc.10`. Both spellings are valid SemVer;
+they are not normalized into one another. Mixing forms also matters:
+`23.1.0-rc.10 < 23.1.0-rc9`, because the first identifier `rc` sorts before
+`rc9`. Switching from `rc9` to `rc.10` would therefore leave `latest` selecting
+`rc9` if both remain eligible. Use an exact pin if SemVer ordering differs
+from the intended upstream RC order.
 
 Linker selectors use the same bzl SemVer comparisons, requirement expressions,
 projection constants, and first/latest selection as LLVM. For example:

From f599b65d2d641af2e23ce8ecbae60efdcb1fe8a0 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:08:54 +0000
Subject: [PATCH 5/7] Show RC selection through the final LLVM release

---
 CHANGELOG.md | 11 +++++++----
 README.md    | 17 +++++++++++------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c51c317b..51d7ca13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,10 +22,13 @@ for release artifacts and the [README](README.md) for configuration and requirem
 - Prerelease eligibility and version constraints are now separate: enable
   prereleases with the corresponding flag, then use ordinary constraints
   without naming a particular RC. For example,
-  `llvm_version = "latest:>23.0,<23.1"` together with
-  `llvm_version_allow_prereleases = True` admits LLVM 23.1.0 RCs but excludes
-  the final 23.1.0 release. The flag admits all prereleases within the range,
-  rather than only those with a release tuple explicitly named in it.
+  `llvm_version = "latest:>23.0,<=23.1"` together with
+  `llvm_version_allow_prereleases = True` follows LLVM 23.1.0 RCs and then
+  selects the final 23.1.0 release once available for the host. Use `<23.1`
+  instead to exclude that final release. The bound `<=23.1` means `<=23.1.0`,
+  not all 23.1.x patches; use `latest:major==23,minor==1` to follow those too.
+  The flag admits all prereleases within the constraints,
+  rather than only those with a release tuple explicitly named in them.
 - Version comparisons now use bzl's SemVer mode. Under
   [SemVer's prerelease ordering rules](https://semver.org/#spec-item-11),
   dot-separated numeric identifiers compare numerically (`rc.2 < rc.10`),
diff --git a/README.md b/README.md
index 74bee482..f1dbde42 100644
--- a/README.md
+++ b/README.md
@@ -314,16 +314,21 @@ always apply. Exact version pins are unaffected.
 ```starlark
 llvm.toolchain(
     name = "llvm_rc",
-    llvm_version = "latest:>23.0,<23.1",
+    llvm_version = "latest:>23.0,<=23.1",
     llvm_version_allow_prereleases = True,
 )
 ```
 
-This admits LLVM 23.1.0 release candidates without naming a particular RC and
-excludes the final 23.1.0 release (`23.1` means `23.1.0`). It selects the newest
-matching version available for the execution host. Stable releases within
-the range remain eligible; append `,is_prerelease()==True` if selection
-must be strictly prerelease-only. With the flag set to `False`, only matching
+This selects the newest matching LLVM 23.1.0 release candidate, then the final
+23.1.0 release once its archive is in the configured catalogue for the execution
+host. Use `latest:>23.0,<23.1` instead to exclude that final release.
+The bound `<=23.1` means `<=23.1.0`: it excludes 23.1.1 and its prereleases.
+To follow all 23.1.x patches and their prereleases, use
+`latest:major==23,minor==1` with the same prerelease flag.
+
+Stable releases within the constraints remain eligible; append
+`,is_prerelease()==True` if selection must be strictly prerelease-only.
+With the flag set to `False`, only matching
 stable releases are eligible. Conversely, `is_prerelease()==False` restricts a
 particular selector to stable releases even when the flag is enabled.
 

From 98c723cc0d8508a9e1ea5711906bd35d640ad994 Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:13:00 +0000
Subject: [PATCH 6/7] Extract 1.13.0 migration details into a dedicated guide

---
 .github/workflows/release_notes_template.txt | 13 +--
 CHANGELOG.md                                 | 30 +-----
 README.md                                    | 43 ++-------
 docs/migration-1.13.0.md                     | 97 ++++++++++++++++++++
 4 files changed, 115 insertions(+), 68 deletions(-)
 create mode 100644 docs/migration-1.13.0.md

diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt
index e1706e6f..e1189190 100644
--- a/.github/workflows/release_notes_template.txt
+++ b/.github/workflows/release_notes_template.txt
@@ -1,14 +1,11 @@
 Minimum bazel version: **7.0.0**
 
 See the [changelog](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/CHANGELOG.md)
-for changes and migration notes for this release. In 1.12.x, `first` / `latest`
-selectors admitted prereleases only when a requirement explicitly specified a
-prerelease version, and only for that same major/minor/patch release. In 1.13.0,
-that explicit requirement is no longer sufficient: also set
-`llvm_version_allow_prereleases = True`, or `linker_version_allow_prereleases = True`
-for catalogued linkers. These flags separate prerelease eligibility from version
-constraints, which no longer need to name an RC. Exact pins, including RC pins,
-are unchanged.
+for changes in this release. In 1.13.0, `first` / `latest` prerelease selection
+requires `llvm_version_allow_prereleases = True`, or
+`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins are
+unchanged. Read the [1.13.0 migration guide](https://github.com/bazel-contrib/toolchains_llvm/blob/{tag}/docs/migration-1.13.0.md)
+for configuration changes, range choices, and SemVer RC ordering.
 
 If you're using `bzlmod`, add the following to `MODULE.bazel`:
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51d7ca13..2cf48d9d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,32 +11,10 @@ for release artifacts and the [README](README.md) for configuration and requirem
 
 ### Migration required for prerelease selectors
 
-- Previously, `first` / `latest` selectors admitted prereleases only when a
-  requirement explicitly specified a prerelease version, and only for that
-  same major/minor/patch release. Starting with 1.13.0, explicitly specifying
-  an RC in a requirement is no longer sufficient: also set
-  `llvm_version_allow_prereleases = True` for LLVM, or
-  `linker_version_allow_prereleases = True` for catalogued linkers. Both options
-  default to `False` and are independent. Exact pins, including RC pins, are
-  unchanged.
-- Prerelease eligibility and version constraints are now separate: enable
-  prereleases with the corresponding flag, then use ordinary constraints
-  without naming a particular RC. For example,
-  `llvm_version = "latest:>23.0,<=23.1"` together with
-  `llvm_version_allow_prereleases = True` follows LLVM 23.1.0 RCs and then
-  selects the final 23.1.0 release once available for the host. Use `<23.1`
-  instead to exclude that final release. The bound `<=23.1` means `<=23.1.0`,
-  not all 23.1.x patches; use `latest:major==23,minor==1` to follow those too.
-  The flag admits all prereleases within the constraints,
-  rather than only those with a release tuple explicitly named in them.
-- Version comparisons now use bzl's SemVer mode. Under
-  [SemVer's prerelease ordering rules](https://semver.org/#spec-item-11),
-  dot-separated numeric identifiers compare numerically (`rc.2 < rc.10`),
-  but identifiers containing letters compare lexically (`rc10 < rc2`).
-  LLVM currently uses undotted RC identifiers, such as `23.1.0-rc3`.
-  A hypothetical `23.1.0-rc10` would therefore sort before `23.1.0-rc2`;
-  mixing forms also gives `23.1.0-rc.10 < 23.1.0-rc9`. Use an exact pin
-  if that differs from the intended upstream RC order.
+- `first` / `latest` prerelease selection now requires an explicit opt-in;
+  specifying an RC in a requirement no longer suffices. Exact pins are unchanged.
+  See the [1.13.0 migration guide](docs/migration-1.13.0.md) for the required
+  flags, range choices, and changed RC ordering under SemVer.
 
 ### Version selection
 
diff --git a/README.md b/README.md
index f1dbde42..58391011 100644
--- a/README.md
+++ b/README.md
@@ -20,16 +20,10 @@ attributes to `llvm_toolchain`.
 
 ### Upgrading to 1.13.0
 
-Previously, `first` / `latest` selectors admitted prereleases only when a
-requirement explicitly specified a prerelease version, and only for that same
-major/minor/patch release. In 1.13.0, that explicit requirement is no longer
-sufficient: also set `llvm_version_allow_prereleases = True` for LLVM, or
-`linker_version_allow_prereleases = True` for catalogued linkers. Exact pins
-(including RC pins) are unchanged. The flag now controls prerelease eligibility
-separately from the constraints, which no longer need to name an RC.
-See the [migration notes](CHANGELOG.md#1130)
-and [requirements examples](#requirements) before upgrading configurations
-that select prereleases.
+`first` / `latest` selectors now require an explicit opt-in to select
+prereleases. Exact pins, including RC pins, are unchanged. Read the
+[1.13.0 migration guide](docs/migration-1.13.0.md) for the required configuration
+changes, range choices, and RC ordering under SemVer.
 
 ## Advanced Usage
 
@@ -307,7 +301,7 @@ Function clauses such as `major()==23` and more advanced inspection are document
 default to `False`. They independently control bare and constrained
 `first`/`latest` selectors for LLVM and catalogued linkers, respectively.
 The flag controls whether prereleases are eligible; the requirements control
-which versions qualify. Constraints no longer need to name an RC, and naming
+which versions qualify. Constraints do not need to name an RC, and naming
 one does not by itself enable prereleases. Requirements and host availability
 always apply. Exact version pins are unaffected.
 
@@ -321,29 +315,10 @@ llvm.toolchain(
 
 This selects the newest matching LLVM 23.1.0 release candidate, then the final
 23.1.0 release once its archive is in the configured catalogue for the execution
-host. Use `latest:>23.0,<23.1` instead to exclude that final release.
-The bound `<=23.1` means `<=23.1.0`: it excludes 23.1.1 and its prereleases.
-To follow all 23.1.x patches and their prereleases, use
-`latest:major==23,minor==1` with the same prerelease flag.
-
-Stable releases within the constraints remain eligible; append
-`,is_prerelease()==True` if selection must be strictly prerelease-only.
-With the flag set to `False`, only matching
-stable releases are eligible. Conversely, `is_prerelease()==False` restricts a
-particular selector to stable releases even when the flag is enabled.
-
-[SemVer compares dot-separated prerelease identifiers](https://semver.org/#spec-item-11)
-numerically when they contain only digits (`rc.2 < rc.10`), but lexically when
-they contain letters (`rc10 < rc2`). LLVM currently uses the undotted form,
-for example [23.1.0-rc3](https://github.com/llvm/llvm-project/releases/tag/llvmorg-23.1.0-rc3),
-not `23.1.0-rc.3`. Between matching `23.1.0-rc2` and hypothetical `23.1.0-rc10`,
-`latest` would choose `rc2`. If LLVM instead used `23.1.0-rc.2` and
-`23.1.0-rc.10`, `latest` would choose `rc.10`. Both spellings are valid SemVer;
-they are not normalized into one another. Mixing forms also matters:
-`23.1.0-rc.10 < 23.1.0-rc9`, because the first identifier `rc` sorts before
-`rc9`. Switching from `rc9` to `rc.10` would therefore leave `latest` selecting
-`rc9` if both remain eligible. Use an exact pin if SemVer ordering differs
-from the intended upstream RC order.
+host. The bound `<=23.1` means `<=23.1.0`, not all 23.1.x patches.
+See the migration guide for [other RC upgrade policies](docs/migration-1.13.0.md#choose-the-scope-of-rc-upgrades)
+and [SemVer RC ordering](docs/migration-1.13.0.md#check-rc-ordering-under-semver),
+including the difference between `rc10` and `rc.10`.
 
 Linker selectors use the same bzl SemVer comparisons, requirement expressions,
 projection constants, and first/latest selection as LLVM. For example:
diff --git a/docs/migration-1.13.0.md b/docs/migration-1.13.0.md
new file mode 100644
index 00000000..c8ab8c25
--- /dev/null
+++ b/docs/migration-1.13.0.md
@@ -0,0 +1,97 @@
+# Migrating to toolchains_llvm 1.13.0
+
+toolchains_llvm 1.13.0 changes prerelease eligibility and version comparisons
+for `first` / `latest` selectors. Configurations selecting prereleases must
+explicitly enable them and review their constraints. Exact version pins,
+including RC pins, are unchanged.
+
+For other changes, see the [1.13.0 changelog](../CHANGELOG.md#1130).
+For the current configuration reference, see [Requirements](../README.md#requirements).
+
+## Enable prereleases explicitly
+
+In 1.12.x, `first` / `latest` selectors admitted prereleases only when a
+requirement explicitly specified a prerelease version, and only for that
+same major/minor/patch release. For example, a requirement naming
+`23.1.0-rc1` admitted other 23.1.0 RCs, but not 23.1.1 or 24.1.0 RCs.
+
+In 1.13.0, naming an RC in a requirement is no longer sufficient. Enable
+prereleases with the corresponding attribute:
+
+- LLVM: `llvm_version_allow_prereleases = True`.
+- Catalogued linkers: `linker_version_allow_prereleases = True`.
+
+Both flags default to `False` and are independent. They apply to bare and
+constrained `first` / `latest` selectors, not exact pins. Use the same attributes
+with `llvm.toolchain` in Bzlmod or `llvm_toolchain` in WORKSPACE; they are also
+available in feature overrides. The linker flag has no effect on bundled
+linkers, `auto`, or absolute executable paths.
+
+The flag now controls prerelease eligibility separately from the constraints.
+Those constraints no longer need to name an RC. Enabling prereleases admits
+every prerelease satisfying them, not just prereleases with a release tuple
+explicitly named in a requirement. For example, adding the flag to
+`latest:>=23.1.0-rc1` also admits later releases' RCs. Review unbounded ranges
+when migrating rather than only adding the flag.
+
+Requirements and execution-host availability always apply. Selection uses
+the configured LLVM or linker catalogue; it does not discover live upstream
+releases. New candidates become available through a toolchains_llvm upgrade
+or an explicit catalogue change.
+
+## Choose the scope of RC upgrades
+
+To follow LLVM 23.1.0 RCs and then select the final 23.1.0 release once its
+archive is available for the execution host:
+
+```starlark
+llvm.toolchain(
+    name = "llvm_rc",
+    llvm_version = "latest:>23.0,<=23.1",
+    llvm_version_allow_prereleases = True,
+)
+```
+
+Choose the range according to the intended upgrade policy. These examples
+all assume `llvm_version_allow_prereleases = True`:
+
+| Selector                    | Upgrade policy                                            |
+| --------------------------- | --------------------------------------------------------- |
+| `latest:>23.0,<23.1`        | Admits 23.1.0 RCs, excludes final 23.1.0.                 |
+| `latest:>23.0,<=23.1`       | Follows 23.1.0 RCs, then selects final 23.1.0.            |
+| `latest:major==23,minor==1` | Follows all 23.1.x releases, including their prereleases. |
+
+`23.1` means `23.1.0`, so `<=23.1` excludes 23.1.1 and its prereleases.
+Stable releases within the constraints remain eligible; for example, the
+two bounded ranges would also admit a 23.0.1 release if present in a custom catalogue.
+Append `,is_prerelease()==True` if selection must be strictly prerelease-only.
+With the flag set to `False`, only matching stable releases are eligible.
+Conversely, `is_prerelease()==False` restricts a particular selector to stable
+releases even when the flag is enabled.
+
+The same constraints work for catalogued linkers through `linker_version`
+with `linker_version_allow_prereleases = True`.
+
+## Check RC ordering under SemVer
+
+Version comparisons now use
+[bzl's SemVer mode](https://mboworks.github.io/bzl/site/tag/0.8.0/docs/versions.html#semver).
+[SemVer compares dot-separated prerelease identifiers](https://semver.org/#spec-item-11)
+numerically when they contain only digits (`rc.2 < rc.10`), but lexically when
+they contain letters (`rc10 < rc2`). `latest` follows that precedence, not
+release chronology.
+
+LLVM uses the undotted form for its 23.1.0 RCs, for example
+[23.1.0-rc3](https://github.com/llvm/llvm-project/releases/tag/llvmorg-23.1.0-rc3),
+not `23.1.0-rc.3`. Between matching `23.1.0-rc2` and hypothetical `23.1.0-rc10`,
+`latest` would choose `rc2`. If LLVM instead used `23.1.0-rc.2` and
+`23.1.0-rc.10`, `latest` would choose `rc.10`.
+
+Both spellings are valid SemVer; they are not normalized into one another.
+Mixing forms also matters: `23.1.0-rc.10 < 23.1.0-rc9`, because the first
+identifier `rc` sorts before `rc9`. Switching from `rc9` to `rc.10` would
+therefore leave `latest` selecting `rc9` if both remain eligible.
+
+Use an exact pin if SemVer ordering differs from the intended upstream RC
+order. Exact pins such as `llvm_version = "23.1.0-rc3"` do not require the
+prerelease flag and bypass `first` / `latest` ordering.

From d899ef152a115ca6b84c3ce63f12d68894a05fed Mon Sep 17 00:00:00 2001
From: helly25 <6420169+helly25@users.noreply.github.com>
Date: Wed, 4 Nov 2026 00:54:11 +0000
Subject: [PATCH 7/7] Include LLVM 23.1.5 in the 1.13.0 release notes

---
 .github/workflows/release_notes_template.txt | 8 ++++----
 CHANGELOG.md                                 | 9 ++++++++-
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release_notes_template.txt b/.github/workflows/release_notes_template.txt
index e1189190..463bcdba 100644
--- a/.github/workflows/release_notes_template.txt
+++ b/.github/workflows/release_notes_template.txt
@@ -15,7 +15,7 @@ bazel_dep(name = "toolchains_llvm", version = "{version}")
 # Configure and register the toolchain.
 llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm")
 llvm.toolchain(
-    llvm_version = "23.1.4",
+    llvm_version = "23.1.5",
 )
 
 use_repo(llvm, "llvm_toolchain")
@@ -24,8 +24,8 @@ use_repo(llvm, "llvm_toolchain")
 register_toolchains("@llvm_toolchain//:all")
 ```
 
-These examples use the linker bundled with LLVM 23.1.4; its macOS linker does
-not require the LLVM 23.1.0–23.1.2 SDK/TAPI workaround. LLVM 23.1.4 has no macOS
+These examples use the linker bundled with LLVM 23.1.5; its macOS linker does
+not require the LLVM 23.1.0–23.1.2 SDK/TAPI workaround. LLVM 23.1.5 has no macOS
 x86_64 archive; Intel Mac users must select another available LLVM version
 through `llvm_version` or `llvm_versions`.
 
@@ -71,7 +71,7 @@ load("@toolchains_llvm//toolchain:rules.bzl", "llvm_toolchain")
 
 llvm_toolchain(
     name = "llvm_toolchain",
-    llvm_version = "23.1.4",
+    llvm_version = "23.1.5",
 )
 
 load("@llvm_toolchain//:toolchains.bzl", "llvm_register_toolchains")
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2cf48d9d..4fb5c7b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,12 +27,19 @@ for release artifacts and the [README](README.md) for configuration and requirem
 - Independent prerelease policies in feature overrides; linker-only policy
   changes can reuse the base LLVM archive.
 
+### LLVM distributions
+
+- Add checksum-pinned LLVM 23.1.5 archives for Linux ARM64/x86_64, macOS ARM64,
+  and Windows ARM64/x86_64. Both xz and zstd metadata are retained; automatic
+  selection continues to use xz. Existing LLVM and mold entries are preserved.
+
 ### Dependencies and publishing
 
 - WORKSPACE dependencies: `rules_cc` 0.2.27, `apple_support` 2.11.0, and
   `bazel_features` 1.54.1.
 - Test dependencies, including `rules_python` 2.4.6, `rules_go` 0.65.0,
-  `rules_foreign_cc` 0.17.0, `rules_rust` 0.75.0, and BoringSSL 0.20261020.0.
+  `rules_foreign_cc` 0.17.0, `rules_rust` 0.75.0, BoringSSL 0.20261020.0,
+  and WORKSPACE `aspect_bazel_lib` 3.8.0.
 - BCR publishing workflow to `publish-to-bcr` 1.6.0.
 
 ## 1.12.0