From 65acef8bb7ad683d221cd18d3e0dd7bd9819e44b Mon Sep 17 00:00:00 2001
From: David Garcia <david@techdocs.studio>
Date: Fri, 14 Aug 2026 16:27:42 +0100
Subject: [PATCH 1/2] docs: build each documented branch's javadoc with the JDK
 it needs

---
 .github/workflows/docs-pages.yml    | 11 ++++------
 README-dev.md                       | 12 ++++++++++
 docs/_utils/javadoc-multiversion.sh | 34 +++++++++++++++++++++++++++++
 docs/_utils/multiversion.sh         |  4 ++--
 4 files changed, 52 insertions(+), 9 deletions(-)
 create mode 100755 docs/_utils/javadoc-multiversion.sh

diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml
index 2cf1569edb9..a00ec3ee705 100644
--- a/.github/workflows/docs-pages.yml
+++ b/.github/workflows/docs-pages.yml
@@ -36,10 +36,12 @@ jobs:
         with:
           python-version: '3.13'
 
-      - name: Set up JDK 11
+      - name: Set up JDK 8 and 11
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: '11'
+          java-version: |
+            8
+            11
           distribution: 'temurin'
 
       - name: Install uv
@@ -53,11 +55,6 @@ jobs:
 
       - name: Build docs
         run: make -C docs multiversion
-        env:
-          # Old release branches (e.g. scylla-4.15.0.x) have javadoc
-          # comments that only pass doclint on JDK 8.
-          # Don't fail their multiversion javadoc builds on JDK 11.
-          MAVEN_OPTS: -Dmaven.javadoc.failOnError=false
 
       - name: Deploy docs to GitHub Pages
         run: ./docs/_utils/deploy.sh
diff --git a/README-dev.md b/README-dev.md
index 07a4673f8a2..b7753317adb 100644
--- a/README-dev.md
+++ b/README-dev.md
@@ -15,6 +15,18 @@ Once you have installed the above software, you can build and preview the docume
 
 To generate the reference documentation of the driver, run the command `make javadoc`. This command generates the reference documentation using the Javadoc tool in the `_build/dirhtml/<VERSION>/api` directory.
 
+## Multiversion build
+
+`make -C docs multiversion` builds the documentation site and javadoc for every branch in `BRANCHES` (`docs/source/conf.py`).
+
+`docs/_utils/javadoc-multiversion.sh` selects the JDK per branch: branches up to `scylla-4.19.0.x` need JDK 8, newer ones JDK 11.
+
+To add a new documented version:
+
+1. Add the branch to `BRANCHES` in `docs/source/conf.py`, and update `LATEST_VERSION` if it is the new latest. New branches build with JDK 11 by default.
+2. Only if the branch needs a different JDK, map it in `docs/_utils/javadoc-multiversion.sh`.
+3. Only if that JDK is not installed by the workflow yet, add it to the `setup-java` step in `.github/workflows/docs-pages.yml`.
+
 ## Using the Makefile
 
 Most day-to-day tasks are wrapped in the top-level `Makefile` so you do not have to remember long Maven invocations. Common targets include:
diff --git a/docs/_utils/javadoc-multiversion.sh b/docs/_utils/javadoc-multiversion.sh
new file mode 100755
index 00000000000..bae205aefc4
--- /dev/null
+++ b/docs/_utils/javadoc-multiversion.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+#
+# Runs each documented version's javadoc.sh with the JDK that version needs.
+
+case "${SPHINX_MULTIVERSION_NAME:-}" in
+  scylla-4.7.2.x | \
+  scylla-4.10.0.x | \
+  scylla-4.11.1.x | \
+  scylla-4.12.0.x | \
+  scylla-4.13.0.x | \
+  scylla-4.14.1.x | \
+  scylla-4.15.0.x | \
+  scylla-4.17.0.x | \
+  scylla-4.18.1.x | \
+  scylla-4.19.0.x)
+    JDK_VERSION=8
+    ;;
+  *)
+    JDK_VERSION=11
+    ;;
+esac
+
+JDK_HOME_VAR="JAVA_HOME_${JDK_VERSION}_X64"
+SELECTED_JDK="${!JDK_HOME_VAR:-}"
+
+if [[ -n "$SELECTED_JDK" ]]; then
+    echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with JDK ${JDK_VERSION} (${SELECTED_JDK})"
+    export JAVA_HOME="$SELECTED_JDK"
+    export PATH="$JAVA_HOME/bin:$PATH"
+else
+    echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with the default JDK (${JDK_HOME_VAR} is not set)"
+fi
+
+exec ./docs/_utils/javadoc.sh
diff --git a/docs/_utils/multiversion.sh b/docs/_utils/multiversion.sh
index 78e0d58ff3e..c6f79c55f14 100755
--- a/docs/_utils/multiversion.sh
+++ b/docs/_utils/multiversion.sh
@@ -1,5 +1,5 @@
-#! /bin/bash	
+#! /bin/bash
 
 cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
     --pre-build "bash -c \"(find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'; find . -mindepth 2 -name README.rst -execdir mv '{}' index.rst ';')\"" \
-    --post-build './docs/_utils/javadoc.sh'
+    --post-build "$(pwd)/docs/_utils/javadoc-multiversion.sh"

From 6cfc08e7cb3e8a0a4083dc9c72af167e9e0d93b7 Mon Sep 17 00:00:00 2001
From: David Garcia <david@techdocs.studio>
Date: Fri, 14 Aug 2026 17:13:29 +0100
Subject: [PATCH 2/2] fix: address coderabbit review

---
 docs/_utils/javadoc-multiversion.sh | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/_utils/javadoc-multiversion.sh b/docs/_utils/javadoc-multiversion.sh
index bae205aefc4..14ae96ef99b 100755
--- a/docs/_utils/javadoc-multiversion.sh
+++ b/docs/_utils/javadoc-multiversion.sh
@@ -27,6 +27,9 @@ if [[ -n "$SELECTED_JDK" ]]; then
     echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with JDK ${JDK_VERSION} (${SELECTED_JDK})"
     export JAVA_HOME="$SELECTED_JDK"
     export PATH="$JAVA_HOME/bin:$PATH"
+elif [[ -n "${GITHUB_ACTIONS:-}" ]]; then
+    echo "${JDK_HOME_VAR} is not set: add JDK ${JDK_VERSION} to the setup-java step in docs-pages.yml" >&2
+    exit 1
 else
     echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with the default JDK (${JDK_HOME_VAR} is not set)"
 fi