Run Dokka in the PR build to catch doc warnings before merge#689
Conversation
The distributed `build-on-ubuntu.yml` ran only `./gradlew build`, which does not run Dokka — Dokka tasks are gated to the publishing graph. With `failOnWarning` enabled, Dokka therefore ran for the first time in the post-merge `Publish` job, so documentation warnings failed CI only after a PR had already been merged. Append `dokkaGenerate` to the Ubuntu build step so the same Dokka run happens during PR review, on every push to the branch. The `Publish` job keeps its own run as a backstop. https://claude.ai/code/session_01QcJcahKjYEXfaVrVrYo5sj
There was a problem hiding this comment.
Pull request overview
This PR updates the shared Ubuntu CI workflow to run Dokka generation during CI so documentation warnings (with failOnWarning) are caught before merge rather than only during the post-merge publish job.
Changes:
- Appends
dokkaGenerateto the Ubuntu CI Gradle invocation (./gradlew build dokkaGenerate --stacktrace). - Adds inline workflow comments explaining why Dokka is executed in CI.
| # `build` does not run Dokka — its tasks are gated to the publishing | ||
| # graph — so `dokkaGenerate` is appended to surface documentation | ||
| # warnings here, during PR review, instead of in the post-merge | ||
| # `Publish` job. `failOnWarning` is enabled in the Dokka setup. | ||
| - name: Build project, run tests, and check documentation |
There was a problem hiding this comment.
Good catch on the wording — I've reworded the comment to "on each push, before merge" so it no longer implies a pull_request trigger.
On the trigger itself: on: push is the pre-existing trigger for this build+test job, so appending dokkaGenerate gives Dokka the same pre-merge coverage the test suite already has — for same-repo branches (this org's model) every push runs the check before merge. These repos intentionally pair Ubuntu (push) with Windows (pull_request), so switching Ubuntu's trigger — and the fork-PR coverage that comes with it — is a broader, org-wide change I'm keeping out of this PR. Happy to follow up separately if you'd like to close the fork-PR gap (likely by also running dokkaGenerate in the pull_request-triggered Windows job).
Generated by Claude Code
Reword the appended comment in `build-on-ubuntu.yml` so it no longer says "during PR review": the workflow is `on: push`, so the Dokka check runs on each push to the branch (before merge), not via the `pull_request` event. Addresses a review note on PR #689. https://claude.ai/code/session_01QcJcahKjYEXfaVrVrYo5sj
Problem
CI repeatedly fails on Dokka documentation warnings during publishing — i.e. after a PR is merged.
The distributed
build-on-ubuntu.ymlran only./gradlew build, which does not run Dokka: Dokka tasks are gated to the publishing graph (isInPublishingGraph()inbuildSrc/.../DokkaExts.kt). WithfailOnWarningenabled, Dokka first ran in the post-merge Publish to Maven repositories job, so documentation warnings surfaced only after the PR was already merged.Fix
Append
dokkaGenerateto the Ubuntu build step, so the command becomes./gradlew build dokkaGenerate --stacktrace.The same Dokka run (with
failOnWarning) now executes during PR review, on every push to the branch — matching what thepre-prskill already runs locally. ThePublishjob keeps its own Dokka run as a backstop, so publish-time behaviour is unchanged.Because
.github-workflows/is merged into each consumer repo's.github/workflows/by./config/pull, this gate ships org-wide on the next update.Notes
failOnWarningis unchanged — still enabled in the shared Dokka setup.Companion PR
SpineEventEngine/agents(branchclaude/magical-cerf-hp5u51) updates the guidelines and skills that previously stated Dokka runs "only in the publish CI job".https://claude.ai/code/session_01QcJcahKjYEXfaVrVrYo5sj
Generated by Claude Code