docs: build each documented branch's javadoc with the JDK it needs - #1004

sequenceDiagram
  participant DocsWorkflow
  participant multiversion.sh
  participant javadoc-multiversion.sh
  participant javadoc.sh
  DocsWorkflow->>multiversion.sh: run documentation build
  multiversion.sh->>javadoc-multiversion.sh: invoke post-build hook
  javadoc-multiversion.sh->>javadoc-multiversion.sh: select and configure JDK
  javadoc-multiversion.sh->>javadoc.sh: execute Javadoc build

Priority: ⬇️ Low

Change: Bug fix

Merge Risk: 🔵 Low · up to ad64e

Local multiversion builds can use an unintended Java version for older branches. The CI path is provisioned, but local setup should be corrected and documented.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands.}

This is the approach that survives DRIVER-1036. That ticket adds scylla-4.x to BRANCHES and makes it LATEST_VERSION; scylla-4.x builds with <release>11</release>, and your allowlist defaults it to JDK 11, so it just works. #1055 (blanket JDK 8) and #909 (scylla-* → JDK 8) both send it to 8 and break. #1055 is mine — closed as superseded.

Two things worth folding in first.

[Major] 🟠 One version's exit code still aborts the whole publish. sphinx-multiversion's run_commands() rescues only OSError, so a non-zero --post-build kills the run and the site publishes nothing — that's why 05-26 → 08-31 passed unnoticed instead of showing as one missing /api/. Cleanest spot is the tail of javadoc-multiversion.sh, which leaves your JDK check above it failing loudly:

-exec ./docs/_utils/javadoc.sh
+if ! ./docs/_utils/javadoc.sh; then
+    echo "::warning::javadoc build failed for ${SPHINX_MULTIVERSION_NAME:-?} - its api pages will be missing"
+fi

[Minor] 🟡 docs/_utils/javadoc.sh has no set -e, and its trailing mv core/target/site/apidocs/* is the only thing setting the exit code — so a failed compile can exit 0. #909 hardens it (set -euo pipefail, site/apidocs → reports/apidocs fallback, fail on empty output). It's branch-owned (sphinx-multiversion runs each checkout's own copy), so it only affects scylla-4.x — which is exactly what DRIVER-1036 turns into a published version. Extract just that file:

git show 9abbc937e96a -- docs/_utils/javadoc.sh | git apply

Worth confirming the output path against maven-javadoc-plugin 3.12.0 with a local make -C docs javadoc before relying on the fallback.

Happy to push either onto your branch or stack them as a follow-up — whichever you prefer.

One addition to the allowlist, while you're in there: #1080 publishes scylla-3.x as a docs version, and it is a Java 8 build (<jdk>[1.8,)</jdk>), so the JDK 11 default would fail its javadoc.

   scylla-4.18.1.x | \
-  scylla-4.19.0.x)
+  scylla-4.19.0.x | \
+  scylla-3.x)
     JDK_VERSION=8

scylla-4.x (#1079) needs no entry — the default is already right for it.

@nikagra edits applied