ci: fail the docs publish when a version loses its javadoc by nikagra · Pull Request #1100 · scylladb/java-driver

nikagra · 2026-09-17T15:38:02Z

Since #1004 made the multiversion post-build tolerant, a failed javadoc only emits a ::warning:: and the run continues. deploy.sh then rebuilds gh-pages from this run's _build/dirhtml and force-pushes, so that version's live /api/ is deleted rather than left stale — and the job stays green. Same silent-failure shape that hid the 2026-05-26 break for three months. gh-pages holds 17 directories today, 16 versions plus stable, each with 619 to 1294 javadoc files.

Check every version conf.py documents, so one missing from the build is caught too, not just the directories the build left behind
Require api/index.html, not merely a non-empty api/
Report the two losses apart: a version that never built is gone from the site entirely, unlike one that published without its javadoc
Deploy unchanged so the versions that did build still publish, then fail. Stop before deploy only when nothing survived, and say the site is untouched rather than describe deletions that never happened

Wanted before #1079, which makes scylla-4.x the LATEST_VERSION — if its javadoc fails there, stable/api is what gets emptied.

Verified: 17 fixture cases, plus 11 deliberate mutations of the guard, each caught by at least one case. The expected version list is written out rather than re-derived by a copy of the guard's own parser, and matches the live gh-pages tree exactly. Docs / Build PR now runs the suite.

Not covered: the publish path itself still never runs before merge (#1103, #1104).

Fixes #1101
Refs: https://scylladb.atlassian.net/browse/DRIVER-1087

🤖 Generated with Claude Code

coderabbitai · 2026-09-17T15:38:09Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: QUIET

Plan: Advanced

Run ID: 580d60ea-e03b-4a1f-b7dd-afd7fa5fdedd

📥 Commits

Reviewing files that changed from the base of the PR and between f597f09 and 9ee21e0.

📒 Files selected for processing (3)

.github/workflows/docs-pages.yml
docs/_utils/check-javadoc-output-test.sh
docs/_utils/check-javadoc-output.sh

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Walkthrough

The workflow now checks generated Javadoc before deployment. The check parses documented versions from conf.py, classifies missing or unusable api/index.html files, writes GitHub outputs and summaries, and fails only when no usable Javadoc remains or configuration parsing fails. Partial losses still deploy, then fail the job. A fixture test script covers build states, aliases, invalid configuration, and real configuration parsing.

Sequence Diagram(s)

sequenceDiagram
  participant DocsWorkflow
  participant check-javadoc-output.sh
  participant BuildOutput
  participant DocsDeploy
  participant GitHubJob
  DocsWorkflow->>check-javadoc-output.sh: Check documented versions
  check-javadoc-output.sh->>BuildOutput: Inspect api/index.html
  check-javadoc-output.sh-->>DocsWorkflow: Return missing versions
  DocsWorkflow->>DocsDeploy: Deploy available documentation
  DocsWorkflow->>GitHubJob: Fail after deployment if versions are missing

Priority: ➖ Normal

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 9ee21

The documentation workflow now detects missing Javadoc, deploys available versions for partial losses, and makes the loss visible by failing the job. No actionable merge risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	[ `#1101` ] `check-javadoc-output.sh` reads `TAGS`, `BRANCHES`, and the stable alias from `docs/source/conf.py`. It requires a non-empty `api/index.html` for each documented version. It writes missing v…
Out of Scope Changes check	✅ Passed	The workflow guard, checker, and fixture tests directly implement [`#1101`]. No unrelated changes are identified in the reviewed change summary or inspected files.
Title check	✅ Passed	The title clearly states that CI will fail documentation publishing when a version loses its Javadoc.
Description check	✅ Passed	The description directly explains the Javadoc guard, deployment behavior, failure conditions, tests, and linked issue.

Full details: Docstring Coverage

Explanation

Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 2 files. (1 skipped: 1 unsupported.)

Fix all pre-merge checks with AI

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.}

A failed javadoc now only warns, and deploy.sh rebuilds gh-pages from the run's output and force-pushes, so that version's live /api/ is deleted while the job stays green. Check every version conf.py documents against the build output, report what was lost to the step summary, deploy so the versions that did build still publish, then fail. A total loss stops before deploy instead, since there would be nothing left worth publishing. Fixture tests cover the guard, and Docs / Build PR runs them. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>

nikagra force-pushed the ci/publish-javadoc-guard branch from 7d9dedc to 3f53f4e Compare September 17, 2026 21:52

nikagra mentioned this pull request Sep 17, 2026

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

Closed

nikagra force-pushed the ci/publish-javadoc-guard branch 2 times, most recently from 731231d to 9ee21e0 Compare September 18, 2026 13:46

nikagra requested a review from dkropachev September 18, 2026 19:19

nikagra marked this pull request as ready for review September 18, 2026 19:19

nikagra force-pushed the ci/publish-javadoc-guard branch from 9ee21e0 to 298a41a Compare September 18, 2026 20:20

dkropachev approved these changes Sep 19, 2026

View reviewed changes

dkropachev merged commit f44efcf into scylladb:scylla-4.x Sep 19, 2026
6 checks passed

This was referenced Sep 21, 2026

ci: build javadoc for the three modules the docs publish #1118

Merged

ci: the javadoc guard passes a partial javadoc loss #1125

Open

Navigation Menu

Repository navigation

ci: fail the docs publish when a version loses its javadoc - #1100

ci: fail the docs publish when a version loses its javadoc#1100
dkropachev merged 1 commit into
scylladb:scylla-4.xfrom
nikagra:ci/publish-javadoc-guard

nikagra commented Sep 17, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 17, 2026 •

edited

Loading

Walkthrough

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Walkthrough

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nikagra commented Sep 17, 2026 •

edited

Loading

coderabbitai Bot commented Sep 17, 2026 •

edited

Loading