Catch KDoc/Javadoc links to `buildSrc` and run Dokka in `pre-pr` by alexander-yevsyukov · Pull Request #13 · SpineEventEngine/agents

alexander-yevsyukov · 2026-06-06T20:50:03Z

Why

A merge into master in tool-base failed its Publish to Maven repositories job in dokkaGeneratePublicationHtml:

w: Couldn't resolve link: [io.spine.gradle.report.coverage.KoverConfig]
   in TestKitCoverage.kt
> Failed with warningCount=2 and errorCount=0

The KDoc linked KoverConfig, a type that lives only in buildSrc — a separate compilation unit Dokka cannot see when documenting a published module. The link never resolved; Dokka is configured to fail on warnings, so the publish job broke even though ./gradlew build (which does not run Dokka) passed locally.

Why the existing tightening didn't catch it

The rule covered path text, not symbol links. The prior API-doc-scope rule forbade mentioning buildSrc/. The offending doc used a symbol link whose package (io.spine.gradle.*) contains no buildSrc substring — invisible to both reviewers and grep.
Nothing ran Dokka before CI. review-docs is advisory; pre-pr runs ./gradlew build, which does not invoke Dokka. And the docs-only path used the bare dokka task, which is ambiguous under Dokka v2 and aborts — the real task is dokkaGenerate.

Changes

guidelines/documentation.md — new section forbidding KDoc/Javadoc links ([Symbol], {@link}, @see, …) to buildSrc/config types, with the failure mechanism and a code-span fix.
skills/review-docs/SKILL.md — matching Must-fix reviewer check; build hint → dokkaGenerate.
skills/pre-pr/SKILL.md — append dokkaGenerate whenever code or docs changed (combined invocation); skip gracefully when Dokka isn't applied; a Dokka failure is a Must-fix.
guidelines/running-builds.md, skills/writer/SKILL.md — replace the broken ./gradlew dokka with dokkaGenerate.

Verification

./gradlew :plugin-testlib:dokkaGenerate in tool-base reproduces the failure on stock master and passes once the doc link is demoted to a code span.

Reach

These files float org-wide via .agents/shared, so the rule and the pre-pr Dokka step apply to every Spine repo on the next pull. Repos without Dokka are unaffected (the step skips gracefully); build/deps-only diffs still run plain build.

🤖 Generated with Claude Code

The `tool-base` publish build failed in `dokkaGeneratePublicationHtml` because a KDoc comment linked `[io.spine.gradle.report.coverage.KoverConfig]`, a type that lives only in `buildSrc`. `buildSrc` is a separate compilation unit Dokka cannot see, so the link never resolved; Dokka fails on warnings, so the publish job broke while `./gradlew build` still passed. The existing API-doc-scope rule only forbade textual mentions of `buildSrc/`, not symbol links whose package (e.g. `io.spine.gradle.*`) carries no `buildSrc` substring. And nothing ran Dokka before CI: `pre-pr` runs `./gradlew build`, which does not invoke Dokka, and the docs-only path used the bare `dokka` task, which is ambiguous under Dokka v2 and aborts. - guidelines/documentation.md: forbid KDoc/Javadoc links to buildSrc/config types, with the failure mechanism and a code-span fix. - review-docs: add the matching Must-fix reviewer check. - pre-pr: append `dokkaGenerate` whenever code or docs changed; skip gracefully when Dokka is not applied; a Dokka failure is a Must-fix. - running-builds.md, writer: replace the broken `./gradlew dokka` with `dokkaGenerate`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

This PR tightens documentation guidance and pre-PR checks to prevent Dokka failures caused by unresolved KDoc/Javadoc symbol links to types that live in buildSrc (a separate compilation unit not visible to Dokka when generating published docs), and standardizes on ./gradlew dokkaGenerate (vs the ambiguous dokka task).

Changes:

Update build-running guidance to prefer ./gradlew dokkaGenerate, and to run Dokka alongside build when code/docs changes could break existing doc links.
Extend documentation/review guidelines to explicitly forbid symbol links (KDoc/Javadoc) to buildSrc / config-only types and explain the remediation.
Update reviewer/pre-PR skills to enforce/encourage the above and treat Dokka failures as Must-fix.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
skills/writer/SKILL.md	Updates validation guidance for doc-only Kotlin/Java changes to prefer `./gradlew dokkaGenerate`.
skills/review-docs/SKILL.md	Adds a Must-fix rule forbidding symbol links to `buildSrc`/`config`-only types; updates Dokka command guidance.
skills/pre-pr/SKILL.md	Updates docs-only build target to `dokkaGenerate` and instructs appending Dokka generation when code/docs change.
guidelines/running-builds.md	Replaces `./gradlew dokka` with `./gradlew dokkaGenerate` and explains why; adds guidance to run Dokka when KDoc/Javadoc could be impacted.
guidelines/documentation.md	Adds a section explicitly forbidding doc links to `buildSrc`/`config` types and provides a recommended rewrite pattern.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 617014005d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…c-links # Conflicts: # skills/pre-pr/SKILL.md

- pre-pr: gate the extra `dokkaGenerate` on `.kt`/`.java` source or doc changes, not the broader `code` class — a pure `*.kts`/build-script edit no longer forces a Dokka run (Codex P2). - documentation.md: make the example a valid KDoc comment (`/** … */`) and stop naming `buildSrc` inside the "right" API-doc sample, consistent with the no-internal-references rule (Copilot + Codex P2). - review-docs: scope the Must-fix to doc comments in published sources; a doc comment under `buildSrc/` linking a sibling `buildSrc` type compiles in the same unit and resolves fine, so it is not flagged (Codex P2). Fix the broken inline code span around the section reference (Copilot). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

- running-builds.md: qualify the "runs HTML and Javadoc" claim — it holds because the Spine config applies both the HTML and Javadoc Dokka plugins; a base-plugin-only project gets HTML alone (Copilot). - claude/commands/run-build.md: replace the broken `./gradlew dokka` with `dokkaGenerate` and mirror the run-Dokka-on-source-change guidance, so the command no longer contradicts the guideline (Copilot). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

alexander-yevsyukov · 2026-06-06T21:17:19Z

@codex, review.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

chatgpt-codex-connector · 2026-06-06T21:19:53Z

Codex Review: Didn't find any major issues. Another round soon, please!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

The extra Dokka run was tied to the fuzzy `docs` token (which includes Markdown). Dokka does not process Markdown, so gate it purely on `.kt`/`.java` source presence in the diff — a code or KDoc/Javadoc-only edit. - pre-pr: proto-only stays `clean build` (Dokka appended only when `.kt`/`.java` also changed); Markdown-only needs no Gradle build; description and checklist reworded to say `.kt`/`.java` source, not "docs" (Copilot x3). - run-build.md: separate the Dokka decision from the base-command bullets so a proto-only or Markdown-only change no longer forces Dokka. - running-builds.md: document that Markdown-only changes need no Gradle build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Per running-builds.md item 3, a KDoc/Javadoc-only edit inside a .kt/.java file should run dokkaGenerate alone - no compile, no tests. The earlier rule ran "build dokkaGenerate" for any .kt/.java change, an unnecessary build/test cycle for doc-only edits (Copilot x2). - pre-pr: split .kt/.java into code vs doc-only; doc-only -> dokkaGenerate (no build/tests); append dokkaGenerate only to a build target, and never double it when it is already the base command. - run-build.md: add the doc-only source bullet and the same don't-double note. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings June 6, 2026 20:50

Copilot started reviewing on behalf of alexander-yevsyukov June 6, 2026 20:50 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Comment thread skills/review-docs/SKILL.md Outdated

Comment thread guidelines/documentation.md

chatgpt-codex-connector Bot reviewed Jun 6, 2026

View reviewed changes

Comment thread skills/pre-pr/SKILL.md Outdated

Comment thread guidelines/documentation.md Outdated

Comment thread skills/review-docs/SKILL.md Outdated

Merge remote-tracking branch 'origin/master' into prevent-buildsrc-do…

346199b

…c-links # Conflicts: # skills/pre-pr/SKILL.md

alexander-yevsyukov self-assigned this Jun 6, 2026

Copilot AI review requested due to automatic review settings June 6, 2026 21:09

Copilot started reviewing on behalf of alexander-yevsyukov June 6, 2026 21:09 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Comment thread guidelines/running-builds.md Outdated

Comment thread guidelines/running-builds.md

alexander-yevsyukov requested a review from Copilot June 6, 2026 21:16

Copilot started reviewing on behalf of alexander-yevsyukov June 6, 2026 21:17 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Comment thread claude/commands/run-build.md Outdated

Comment thread skills/pre-pr/SKILL.md Outdated

Comment thread skills/pre-pr/SKILL.md Outdated

alexander-yevsyukov requested a review from Copilot June 6, 2026 21:32

Copilot started reviewing on behalf of alexander-yevsyukov June 6, 2026 21:32 View session

Copilot AI reviewed Jun 6, 2026

View reviewed changes

Comment thread skills/pre-pr/SKILL.md Outdated

Comment thread claude/commands/run-build.md Outdated

alexander-yevsyukov requested a review from armiol June 6, 2026 21:47

alexander-yevsyukov changed the title ~~Catch KDoc/Javadoc links to buildSrc and run Dokka in pre-pr~~ Catch KDoc/Javadoc links to buildSrc and run Dokka in pre-pr Jun 7, 2026

alexander-yevsyukov changed the title ~~Catch KDoc/Javadoc links to buildSrc and run Dokka in pre-pr~~ Catch KDoc/Javadoc links to buildSrc and run Dokka in pre-pr Jun 7, 2026

armiol approved these changes Jun 7, 2026

View reviewed changes

alexander-yevsyukov merged commit 6fea0a0 into master Jun 7, 2026

alexander-yevsyukov deleted the prevent-buildsrc-doc-links branch June 7, 2026 15:36

Conversation

alexander-yevsyukov commented Jun 6, 2026

Why

Why the existing tightening didn't catch it

Changes

Verification

Reach

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

alexander-yevsyukov commented Jun 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot commented Jun 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants