ci: build docs javadoc with JDK 8 again

.github/workflows/docs-pages.yml

@@ -36,10 +36,21 @@ jobs:
         with:
           python-version: '3.13'
 
-      - name: Set up JDK 11
+      # Pinned to JDK 8 on purpose, and not the same choice as docs-pr.yml.
+      # That workflow runs `make -C docs test`, which builds only the current
+      # branch -- scylla-4.x, which is post "build: drop Java 8 support" and so
+      # is fine on 11. This one runs `make -C docs multiversion`, which builds
+      # EVERY version in conf.py's BRANCHES, LATEST_VERSION included. All of
+      # them are frozen release branches that predate that commit and compile
+      # via error-prone's javac 9 shim; it cannot read JDK 11 class files and
+      # fails with "class file has wrong version 55.0, should be 53.0".
+      # scylla-4.x is not itself in BRANCHES, so nothing built here needs a
+      # newer JDK. Do not raise this without building the newest branch in
+      # BRANCHES on the new JDK first.
+      - name: Set up JDK 8.0
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: '11'
+          java-version: '8'
           distribution: 'temurin'
 
       - name: Install uv
@@ -53,11 +64,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

docs/_utils/multiversion.sh

@@ -1,5 +1,11 @@
 #! /bin/bash	
 
+# javadoc.sh comes from each version's own tree and runs a full Maven build, so
+# it can break on a frozen release branch for reasons unrelated to the docs.
+# sphinx-multiversion's run_commands() only rescues OSError, so an exit code
+# there aborts the whole multiversion run and the site publishes nothing -- that
+# is how every build between 2026-05-26 and 2026-08-31 was lost. Degrade to a
+# missing /api/ for the one version instead, and say so in the log.
 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 "bash -c './docs/_utils/javadoc.sh || echo \"::warning::javadoc build failed for \$SPHINX_MULTIVERSION_NAME - its api pages will be missing\"'"