From 8417026756c8777127ed3ae256d380ecd6ddcf49 Mon Sep 17 00:00:00 2001
From: patwie <mail@patwie.com>
Date: Wed, 22 Jul 2026 22:09:11 +0000
Subject: [PATCH] ci: Document and verify Eigen 5 compatibility

Agents and users integrating the Bazel module routinely misread the
declared `eigen 3.4.0.bcr.3` dependency as a pin and conclude the
library only works with old Eigen. Under bzlmod it is a minimum:
version selection resolves to the highest Eigen requested anywhere in
the module graph, and every BCR eigen release from 3.4.0 through 5.x
shares compatibility_level 1.

Make this explicit in the README integration section and next to the
bazel_dep itself, and add a dedicated workflow that appends a
single_version_override for the newest BCR Eigen 5 release and runs
the full test suite, so the compatibility claim stays verified as new
Eigen versions land. The override is appended in CI rather than
committed because single_version_override is only honored in the root
module and would otherwise force the pin on consumers.
---
 .github/workflows/eigen5.yml | 52 ++++++++++++++++++++++++++++++++++++
 MODULE.bazel                 |  5 ++++
 README.md                    | 13 ++++++++-
 3 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/eigen5.yml

diff --git a/.github/workflows/eigen5.yml b/.github/workflows/eigen5.yml
new file mode 100644
index 0000000..43ce119
--- /dev/null
+++ b/.github/workflows/eigen5.yml
@@ -0,0 +1,52 @@
+name: Eigen 5 Compatibility
+
+# The Bazel module declares eigen 3.4.0.bcr.3 as its minimum, so the main
+# CI workflow exercises the compatibility floor. This workflow verifies the
+# other end of the supported range: it forces the module graph onto the
+# newest Eigen 5 release in the BCR and runs the full test suite, keeping
+# the "compatible with Eigen 3.4 through 5.x" claim in the README honest.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  # Newest Eigen in the Bazel Central Registry. Bump when a new release
+  # lands: https://registry.bazel.build/modules/eigen
+  EIGEN_VERSION: 5.0.1.bcr.2
+
+jobs:
+  eigen5:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Bazel 9
+        uses: bazel-contrib/setup-bazel@0.19.0
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}
+          repository-cache: true
+
+      - name: Override Eigen to ${{ env.EIGEN_VERSION }}
+        # single_version_override is only honored in the root module, so it
+        # cannot live in the committed MODULE.bazel without also forcing the
+        # pin on consumers. Appending it here keeps the override CI-only.
+        run: |
+          cat >> MODULE.bazel <<EOF
+
+          single_version_override(
+              module_name = "eigen",
+              version = "${EIGEN_VERSION}",
+          )
+          EOF
+
+      - name: Test against Eigen ${{ env.EIGEN_VERSION }}
+        run: |
+          bazel test //... \
+            --copt=-Wall --copt=-Wextra --copt=-Wpedantic \
+            --copt=-Wdouble-promotion --copt=-Werror
diff --git a/MODULE.bazel b/MODULE.bazel
index ec96b60..1ba5517 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -5,5 +5,10 @@ module(
 )
 
 bazel_dep(name = "rules_cc", version = "0.0.17")
+
+# Minimum supported Eigen, not a pin. Bzlmod selects the highest version
+# requested anywhere in the module graph, and all BCR eigen releases
+# (3.4.0 through 5.x) share compatibility_level 1, so consumers on
+# Eigen 5.x build cppoptlib against Eigen 5 automatically.
 bazel_dep(name = "eigen", version = "3.4.0.bcr.3")
 bazel_dep(name = "googletest", version = "1.17.0.bcr.2", dev_dependency = True)
diff --git a/README.md b/README.md
index cd30fb0..3a5fdb5 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,10 @@ int main() {
 
 ## Integration
 
-The only dependency is Eigen3.
+The only dependency is Eigen3. **Compatible with Eigen 3.4 through
+Eigen 5.x** — the versions referenced below are minimums, not pins.
+If your project already uses Eigen 5, cppoptlib builds against it
+unchanged.
 
 ### CMake (FetchContent)
 
@@ -100,6 +103,14 @@ cc_binary(
 )
 ```
 
+cppoptlib declares `eigen 3.4.0.bcr.3` as its *minimum*. To build
+against Eigen 5, simply request it in your own `MODULE.bazel` —
+bzlmod resolves to the highest requested version:
+
+```starlark
+bazel_dep(name = "eigen", version = "5.0.1.bcr.2")
+```
+
 ## Solvers
 
 | Solver | Header | Order | Constraints |