Released versions are never registered with the docs site: /stable/ is 4.19.0.1, driver is 4.19.2.1 #1056

Summary

/stable/ on the documentation site is built from a tree frozen at tag 4.19.0.1
(2025-04-07), while the released driver is 4.19.2.1 (2026-08-17). Registering a released
version with the documentation site is a manual step that nothing documents or automates, and it
has been skipped for every release since 4.19.0.1.

This is the diagnosis behind #302, which reports the symptom with a screenshot.

How a version gets published

docs/source/conf.py on scylla-4.x is the whole mechanism. TAGS = [], so only branches are
published; sphinx-multiversion filters refs by smv_branch_whitelist = multiversion_regex_builder(BRANCHES) and smv_remote_whitelist = r'^origin$'. A version appears
only if a scylla-<version>.x branch exists on origin and is listed in BRANCHES.
smv_rename_latest_version = 'stable' makes /stable/ whatever LATEST_VERSION names — currently
scylla-4.19.0.x.

Two things are wrong

1. scylla-4.19.0.x was never moved forward. It sits at tag 4.19.0.1 plus four docs-only
commits from May 2025 — 239 commits behind tag 4.19.0.9, and 4.19.0.9 is neither an ancestor
nor a descendant of it. The commit that created the branch, 1d0c9185ed ("Add recent releases to
documentation versions list"), called this out at the time:

Note that scylla-4.19.0.x corresponds to the latest released 4.19.0.1 and not current master
(scylla-4.x). If the next released version is 4.19.0.2 then scylla-4.19.0.x will need to be
moved with whatever documentation backports it has on top of 4.19.0.2.

4.19.0.2 shipped 2025-11-08. The branch was never moved.

2. There is no scylla-4.19.2.x branch at all. The convention is one docs branch per released
upstream minor.patch line, and 10 of the 12 released 4.x lines have one. The gaps are 4.18.0
(harmless — superseded three days later by 4.18.1, which does have a branch) and 4.19.2,
which nothing supersedes and which is the newest released line.

Why it keeps happening

Nothing owns the step.

• .github/workflows/release.yml creates the version tag and the two [maven-release-plugin]
  commits and pushes with git push origin --follow-tags. It never runs git branch or
  mvn release:branch, and it never references docs/source/conf.py.
• CONTRIBUTING.md and README-dev.md have no release section. There is no RELEASE* file or
  checklist anywhere in the tree, no issue/PR template, and the wiki is empty.
• Consequently every BRANCHES change in history is a standalone, hand-written docs PR landing
  weeks to months after the releases it documents — most recently docs: Add recent releases to documentation versions list #532 and Add new 3.x branches to documentation config #552.
• The 4.19.2.0 release PR (Merge upstream apache/cassandra-java-driver 4.19.2 and bump version to 4.19.2.0 #895) bumped every pom and changelog/README.md but did not touch
  docs/source/conf.py and cut no branch.

Impact

Content that exists on scylla-4.x and has no published home:

• upgrade_guide/README.md → ### 4.19.2.1, documenting the new SESSION_ID and DRIVER_CONFIG
STARTUP options. /stable/upgrade_guide/ currently starts at ### 4.18.1.
• changelog/README.md → ### 4.19.1 and ### 4.19.2. /stable/'s changelog stops at
  ### 4.19.0.
• manual/core/request_id/ and upgrade_guide/from_3x/ — new pages that 404 at /stable/.

A reader upgrading to 4.19.2.1 cannot find its upgrade notes on the site.

Proposed fix

1. Cut scylla-4.19.2.x at the 4.19.2.1 release point, matching how the existing docs branches
   sit at a release tag plus docs-only commits.
2. On scylla-4.x, in docs/source/conf.py: append 'scylla-4.19.2.x' to BRANCHES and set
   LATEST_VERSION = 'scylla-4.19.2.x'. /stable/ then follows automatically and
   scylla-4.19.0.x stays published as a previous version. Do not add it to
   scylladb_markdown_recommonmark_versions — doc: remove new versions from scylladb_markdown_recommonmark_versions #557 asks for the opposite.
3. Decide whether scylla-4.19.0.x should be re-pointed at 4.19.0.9 or simply left as the
   4.19.0.1 snapshot now that a newer line is published.
4. Make 1+2 an explicit, written release step — a checklist in CONTRIBUTING.md at minimum, or
   automation in release.yml. This is the actual defect; without it the next release skips it
   again.

Note that docs-pages.yml triggers on push to scylla-** with
paths: docs/**, faq/**, manual/**, changelog/**, upgrade_guide/**, so creating the branch alone
does not trigger a rebuild — the conf.py edit in step 2 is what does.

Not fixed by #1055

#1055 fixes Docs / Publish failing since 2026-05-26 (JDK 11 vs the frozen branches' error-prone
javac shim). That restores publishing, but /stable/ will still be scylla-4.19.0.x afterwards.
Both changes are needed, in either order. The two interacted only by coincidence: #895's merge
triggered the last green publish on 2026-05-22, the publish broke two days later, and both 4.19.2
tags shipped after that — so the missing version would not have appeared regardless.

Related: #302 (symptom, should be closed by this), #557 (the other per-version list in the same
conf.py), #157 (incomplete published javadocs).

Tracked as DRIVER-1036.