Skip to content

docs: publish scylla-4.x as the stable docs version (DRIVER-1036) - #1079

Closed
nikagra wants to merge 1 commit into
scylladb:scylla-4.xfrom
nikagra:docs-publish-scylla-4x
Closed

docs: publish scylla-4.x as the stable docs version (DRIVER-1036)#1079
nikagra wants to merge 1 commit into
scylladb:scylla-4.xfrom
nikagra:docs-publish-scylla-4x

Conversation

@nikagra

@nikagra nikagra commented Sep 14, 2026

Copy link
Copy Markdown

BRANCHES in docs/source/conf.py already lists every release branch that exists upstream, so there is nothing left to register and /stable/ stays pinned to scylla-4.19.0.x — a branch sitting at 4.19.0.1-4-gf117e2b896, cut long before client routes landed. Everything merged to scylla-4.x since is invisible on the site, including the client-routes section in manual/core/address_resolution/.

  • Add scylla-4.x to BRANCHES and make it LATEST_VERSION, so /stable/ is the development tip.
  • Repoint the deprecation banner's migration link at upgrade_guide/from_3x/ — its comment deferred exactly this until /stable/ carried that page.
  • TAGS stays empty, and scylla-4.x stays out of scylladb_markdown_recommonmark_versions, which is what selects MyST for its {eval-rst} fences.

This follows the sibling drivers rather than inventing a policy: gocql has LATEST_VERSION = "master", cpp-driver has BRANCHES = ['master'] and LATEST_VERSION = 'master', both with TAGS = []. The trade-off is that /stable/ now means "development tip", not "newest release branch".

Verified: make -C docs test green under -W --keep-going; sphinx-multiversion --dump-metadata lists 17 versions with scylla-4.x among them; multiversion_regex_builder(BRANCHES) matches scylla-4.x, and LATEST_VERSION is in BRANCHES as conf.py requires. Not covered: the full 17-version publish, which only runs post-merge.

Stacked on #1004 — Docs / Publish has been red on every run since 2026-05-26, so nothing reaches the site until that lands. scylla-4.x builds with <release>11</release>, which is why #1004's per-branch JDK map is the prerequisite here and a blanket JDK 8 is not.

Fixes DRIVER-1036

🤖 Generated with Claude Code

@nikagra @claude
docs: publish scylla-4.x as the stable docs version (DRIVER-1036)
dbd6535 
BRANCHES already lists every release branch that exists upstream, so no
release is left to register and /stable/ stays at scylla-4.19.0.x, frozen
four months before client routes landed.

Publish scylla-4.x and make it LATEST_VERSION, matching gocql and
cpp-driver, which both publish their development branch as stable.

/stable/ now carries upgrade_guide/from_3x/, so the deprecation banner's
migration link points straight at it, as its comment anticipated.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@coderabbitai

coderabbitai Bot commented Sep 14, 2026

Copy link
Copy Markdown

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.

This was referenced Sep 14, 2026
Closed
Merged
Merged
Merged
Closed
Open
@nikagra

nikagra commented Sep 17, 2026

Copy link
Copy Markdown
Author

Blocked by #1111. Pre-flighting docs/_utils/javadoc.sh on scylla-4.x under JDK 11 — the arm this PR would be the first to exercise — fails: coverage-report cannot resolve integration-tests, which mvn install skips installing. The script exits 1 before creating api/.

Merging as-is would publish scylla-4.x and stable with an empty api/, replacing the 1294 files currently live at /stable/api/. coverage-report postdates every branch in BRANCHES, which is why the 2026-09-17 publish was green at 17/17.

One-line fix in #1111 (-pl core), verified. #1100 lands first so a recurrence is loud rather than silent.

@nikagra nikagra mentioned this pull request Sep 21, 2026
Merged
@nikagra

nikagra commented Sep 24, 2026

Copy link
Copy Markdown
Author

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 nikagra closed this Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

area/Driver_-_java-driver-4.x P3

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nikagra