docs: deprecate Java Driver 3.x and announce maintenance mode

[nikagra]

DRIVER-854: Deprecating Java Driver 3.x

Announces that Java Driver 3.x is deprecated and in maintenance mode. Part of DRIVER-483,
tracked as DRIVER-854.

README.md only: the deprecation notice at the top with a link to 4.x, and the version references
updated from 3.11.5.0 to 3.11.5.17 (the current latest 3.x release).

This PR is the announcement. The migration route is #1001 and the docs-site notice is #997, so that
the three review independently.

No changelog entry

An earlier revision added one to changelog/README.md. Dropped: that file records upstream
releases only — every commit that has ever touched it is an upstream merge or an upstream
release-prep commit, and no ScyllaDB release (3.11.5.1 … 3.11.5.17) appears in it. Fork releases
are documented in GitHub Releases, which is where a reader looks for them. A fork-lifecycle notice
wedged into a list of upstream versions would be the only entry of its kind.

Which PR the site actually sees

PR	Branch	Reaches
#919 (this one)	scylla-3.x	GitHub readers of the 3.x branch
#1001	scylla-3.x	GitHub readers — the 4.x migration route
#997	scylla-4.x	the published documentation site, all six 3.x versions

The docs-site half cannot live here. docs-pages.yml checks out
${{ github.event.repository.default_branch }} on every publish regardless of which branch was
pushed, and scylla-3.x is not a published doc version at all —
/scylla-3.x/ returns 404. sphinx-multiversion
takes page content from each version's own ref but conf.py and templates_path from the publishing
branch, so both DEPRECATED_VERSIONS and the deprecation banner only take effect there.

An earlier revision of this PR also edited docs/source/conf.py and
docs/source/_templates/notice.html on this branch; both were dropped as no-ops for the published
site. To be clear about why: a _templates/ override is a perfectly good mechanism — it is exactly
what #997 now uses to reach the frozen 3.x branches — it just has no effect from here.

What this means

• Java Driver 3.x enters maintenance mode — only critical bug fixes will be accepted.
• Users are directed to migrate to Java Driver 4.x.
• Once docs: deprecate the 3.x doc versions and route their readers to 4.x #997 is merged and published, every page of all six published 3.x doc versions carries a
  deprecation notice with a link to the migration guide. (The version picker itself is not marked;
  the theme has no mechanism for that.)

Remaining DRIVER-483 tasks (out of scope for this PR)

• DRIVER-852 Inventory of internal tools using java-driver 3.x — published
• DRIVER-853 Inventory of external tools and integrations using java-driver 3.x
• DRIVER-855 Publish the deprecation announcement in internal and external documentation
  portals — gates the merge of these three PRs, per the request to coordinate with the other
  customer-communication channels first
• DRIVER-856 Prepare and publish a performance comparison blog post
• DRIVER-938 Query system.clients to find deployed 3.x consumers

[coderabbitai]

📝 Walkthrough

Walkthrough

The README and changelog now mark Java Driver 3.x as deprecated and in maintenance mode. They direct new development to Driver 4.x and document the critical-fixes policy. README release references, Maven dependency examples, and compatibility information now use version 3.11.5.17.

Possibly related PRs

• scylladb/java-driver#997: Adds a similar Java Driver 3.x deprecation notice and updates documentation-site version metadata.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: deprecating Java Driver 3.x and announcing maintenance mode.
Description check	✅ Passed	The description directly explains the deprecation, maintenance mode, version updates, documentation scope, and related work.

---

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

[annastuchlik]

@mikliapko When this PR is merged and the information is published with the new driver release, we need to update the generic Drivers page and driver support to indicate that 3.x is deprecated.
https://docs.scylladb.com/stable/drivers/cql-drivers.html
https://docs.scylladb.com/stable/versioning/driver-support.html

Sources at https://github.com/scylladb/scylladb-docs-homepage/tree/main/docs

[mikliapko]

@mikliapko When this PR is merged and the information is published with the new driver release, we need to update the generic Drivers page and driver support to indicate that 3.x is deprecated. https://docs.scylladb.com/stable/drivers/cql-drivers.html https://docs.scylladb.com/stable/versioning/driver-support.html

Sources at https://github.com/scylladb/scylladb-docs-homepage/tree/main/docs

I suppose it's @nikagra who should have been tagged :)

[annastuchlik]

I suppose it's @nikagra who should have been tagged :)

True, sorry!

[nikagra]

Rebased onto current scylla-3.x and revised. Two changes worth flagging for review:

• Dropped the docs/source/conf.py and docs/source/_templates/notice.html edits. Neither reached the published site: docs-pages.yaml checks out the default branch (scylla-4.x) on every publish, and scylla-3.x is not a published doc version. That half now ships as docs: deprecate the 3.x doc versions and route their readers to 4.x #997 against scylla-4.x, which is the only conf.py the site build reads.
• Version references now point at 3.11.5.17 (was 3.11.5.15, superseded while this sat as a draft), and the changelog entry cites DRIVER-483 rather than DRIVER-632, which is closed as a duplicate of it.

@annastuchlik — per your comment above, the scylladb-docs-homepage pages are recorded on DRIVER-855 so they are picked up once this is released.

[coderabbitai]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (2)

README.md-9-9 (1)

9-9: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Capitalize GitHub in the prose.

Change github.com to GitHub. Keep the URL domain lowercase.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 9, Update the README prose around the GitHub reading note
to capitalize the brand name as “GitHub,” while preserving the lowercase
`github.com` URL domain.

Source: Linters/SAST tools

README.md-92-92 (1)

92-92: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Update the object-mapper dependency documentation.

Line [92] now uses 3.11.5.17, but manual/object_mapper/README.md still documents 3.11.5.0. Update that example so users do not receive conflicting release instructions.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 92, Update the object-mapper version example in
manual/object_mapper/README.md from 3.11.5.0 to 3.11.5.17 so it matches the
version documented in README.md.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Other comments:
In `@README.md`:
- Line 9: Update the README prose around the GitHub reading note to capitalize
the brand name as “GitHub,” while preserving the lowercase `github.com` URL
domain.
- Line 92: Update the object-mapper version example in
manual/object_mapper/README.md from 3.11.5.0 to 3.11.5.17 so it matches the
version documented in README.md.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Pro Plus

Run ID: 4c3d68fa-3431-4778-99c8-9fd57c817205

📥 Commits

Reviewing files that changed from the base of the PR and between 855dc8c and 97b95eb.

📒 Files selected for processing (2)

• README.md
• changelog/README.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• scylladb/github-automation (auto-detected)
• scylladb/scylladb (auto-detected)