docs: publish the scylla-3.x maintenance branch (DRIVER-1083) by nikagra · Pull Request #1080 · scylladb/java-driver

nikagra · 2026-09-14T18:43:20Z

scylla-3.x is not in BRANCHES, so the newest published 3.x docs come from scylla-3.11.5.x — a
branch frozen 2025-06-02, pom.xml at 3.11.5.7. The releases moved: tags 3.11.5.16, .17 and
.18 are all cut from scylla-3.x, along with the release-plugin commits. So someone who installs
3.11.5.18 and reads /scylla-3.11.5.x/ gets documentation for a build eleven patch releases older,
under a name implying it covers their version.

Add scylla-3.x to BRANCHES, and to DEPRECATED_VERSIONS so it keeps the caution banner.
Empty hide_version_dropdown. 308ccd8e94 put scylla-3.x there in the same commit that first
published it — build the then-default branch, don't advertise it. Since sitemap_url_scheme
covers only /stable/, keeping it would leave the branch reachable by direct URL alone.
Add scylla-3.x to the guard fixtures' REAL_ALL, which tracks BRANCHES.

134 commits of content become visible, including #1081's client-routes section, the 3.11.5.19
upgrade notes, and #919's deprecation notice — which currently has no published home.

Verified with a local make -C docs multiversion over scylla-3.x + scylla-4.19.0.x, javadoc
post-build stubbed: 3.x appears in the version dropdown, its pages carry the banner with the
migration link resolving to /stable/upgrade_guide/, and the stranded sections render.
./docs/_utils/check-javadoc-output-test.sh passes, and fails without the REAL_ALL edit. The
javadoc path for this branch is #1124, already merged. Not covered: the 17-version publish, which
only runs post-merge.

No longer stacked on #1079 — this stands alone on scylla-4.x, and #1079 will need a rebase.

Fixes DRIVER-1083

🤖 Generated with Claude Code

coderabbitai · 2026-09-14T18:43:27Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

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.

❤️ Share

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

maven-javadoc-plugin moved the javadoc goal's output from target/site/apidocs to target/reports/apidocs in 3.11, and this branch pins 3.11.3. The script still copies from target/site, so the glob never matches, mv fails, and api/ publishes empty. The frozen scylla-3.*.x branches pin 2.10.4, which is why scylla-3.x has gone unnoticed: it is not a published docs version yet. Resolve from either location, clear both first so the fallback is unambiguous, and require a real non-empty index.html. Build only driver-core: with set -e in force, a javadoc failure in another module would otherwise cost the whole api/. Fixes scylladb#1123 Refs: scylladb#1080, scylladb#1118 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

maven-javadoc-plugin moved the javadoc goal's output from target/site/apidocs to target/reports/apidocs in 3.11, and this branch pins 3.11.3. The script still copies from target/site, so the glob never matches, mv fails, and api/ publishes empty. The frozen scylla-3.*.x branches pin 2.10.4, which is why scylla-3.x has gone unnoticed: it is not a published docs version yet. Resolve from either location, clear both first so the fallback is unambiguous, and require a real non-empty index.html. Build only driver-core: with set -e in force, a javadoc failure in another module would otherwise cost the whole api/. Fixes #1123 Refs: #1080, #1118 Co-authored-by: Claude Opus 5 (1M context) <[email protected]>

scylla-3.x is not in BRANCHES, so the newest published 3.x docs come from scylla-3.11.5.x, frozen 2025-06-02 at 3.11.5.7 -- eleven releases behind 3.11.5.18, which ships from scylla-3.x. 134 commits are stranded, including the scylladb#919 deprecation notice. Publish it, and mark it deprecated so it keeps the caution banner. Empty hide_version_dropdown: 308ccd8 added the name in the same commit that first published the branch, and the sitemap covers only /stable/, so hiding it leaves the docs reachable by direct URL alone. REAL_ALL tracks BRANCHES, so the guard's fixtures gain the version. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

nikagra · 2026-09-24T12:44:43Z

Closing: publishing the generic line branch is the wrong shape, and the version dropdown is why.

sphinx_multiversion/sphinx.py:_version_key tries a PEP 440 parse of the branch name and falls back
to the raw string:

scylla-4.19.0.x  -> (0, Version('4.19.0'))
scylla-3.11.5.x  -> (0, Version('3.11.5'))
scylla-3.x       -> (1, 'scylla-3.x')     # unparseable
scylla-4.x       -> (1, 'scylla-4.x')     # unparseable

Every (0, …) sorts before every (1, …), and versions.html:12 renders
versions.branches|reverse — so an unparseable name comes out first. Publishing both would give:

1. 4.x   2. 3.x   3. 4.19.0.x   4. 4.18.1.x  ...

A deprecated maintenance branch above current stable, with no deprecation marker in the selector
(versions_deprecated only drives the banner). The theme exposes no ordering option, and the sort
lives in sphinx-multiversion-scylla, a separate repo.

There is a second reason. The theme renders only current_version.name — grepping the whole of
sphinx_scylladb_theme for .version, .release or is_released finds nothing, and no conf.py
in this repo sets version/release anyway (all refs report ''). The branch name is the only
version identity the site has, so a name like 3.x or 4.x tells a reader nothing about which
driver the page documents.

Superseded by cutting precise version branches instead: scylla-4.19.2.x from the 4.19.2.2 tag, and
re-cutting scylla-3.11.5.x from 3.11.5.19. Both parse, so both sort correctly, and both name a real
release. Tracked under DRIVER-1036.

nikagra mentioned this pull request Sep 14, 2026

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

Merged

github-actions Bot added the P3 label Sep 14, 2026

This was referenced Sep 14, 2026

docs: note that client routes are 4.x-only (DRIVER-1043) #1081

Merged

docs: README-dev describes the multiversion JDK choice as a version range #1109

Open

ci: docs publish deletes a version's javadoc silently when its build fails #1101

Closed

This was referenced Sep 22, 2026

ci: scylla-3.x would publish an empty api/, javadoc.sh reads the pre-3.11 output path #1123

Closed

ci: read javadoc output from target/reports on scylla-3.x #1124

Merged

nikagra force-pushed the docs-publish-scylla-3x branch from ee2e9ed to 23f65ee Compare September 24, 2026 10:31

nikagra closed this Sep 24, 2026

Navigation Menu

Repository navigation

docs: publish the scylla-3.x maintenance branch (DRIVER-1083) - #1080

docs: publish the scylla-3.x maintenance branch (DRIVER-1083)#1080
nikagra wants to merge 1 commit into
scylladb:scylla-4.xfrom
nikagra:docs-publish-scylla-3x

nikagra commented Sep 14, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 14, 2026

Draft PR not reviewed

Uh oh!

nikagra commented Sep 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

nikagra commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 14, 2026

Draft PR not reviewed

Uh oh!

nikagra commented Sep 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

nikagra commented Sep 14, 2026 •

edited

Loading