Generate reference docs from a kagent release tag, not from main - #500
Merged
Merged
Conversation
The nightly reference-docs job has failed since 2026-09-22 with
x/tools@v0.19.0/internal/tokeninternal/tokeninternal.go:64:9:
invalid array length -delta * delta (constant -256 of type int64)
Nothing changed in kagent or the docs. Setup Go asks for 'stable', so
GitHub runners picked up Go 1.27.1 and rebuilt crd-ref-docs against it.
crd-ref-docs v0.1.0 depends on golang.org/x/tools v0.19.0, whose
internal/tokeninternal carries a compile-time size assertion on
go/token.File; Go 1.27 changed that struct, so the assertion fails and
the step dies before generating anything.
x/tools removed the file in v0.35.0, which crd-ref-docs v0.2.0 depends
on, so the bump clears it. Verified under a real Go 1.27.1 toolchain
against kagent main's go/api/v1alpha3: v0.1.0 reproduces the failure,
v0.2.0 and v0.3.0 both generate.
All 74 headings are identical across v0.1.0, v0.2.0 and v0.3.0, so the
provider pages that link to crd-ref-docs anchors (#modelconfigspec,
#openaiconfig, ...) are unaffected. v0.2.0 is the near-drop-in at 6
bytes of output difference: it collapses blank lines inside Go doc
comments, flattening <br /><br /> to <br /> in seven prose-heavy
fields, and gains accurate items:MinLength on array fields. v0.3.0 was
left on the table because it appends Required: {} / Optional: {} to all
244 Validation rows, which Hextra renders as literal braces.
The rest of the job is Go 1.27-clean: helm-docs v1.14.2 has no x/tools
dependency, and both CLI binaries build and smoke-test.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Takes crd-ref-docs to v0.3.0 rather than v0.2.0. Both clear the Go 1.27
build failure; v0.3.0 additionally marks which fields are required,
which nothing before it did. The reference currently gives a reader no
way to tell a required field from an optional one -- 67 required fields
across the v1alpha3 types, none of them marked.
v0.3.0 pays for that by stamping all 244 rows of the Validation column
with `Required: \{\}` or `Optional: \{\}`, which Hextra renders as a
literal `{}`. Both generation steps now normalize the markers: optional
is the default, so its 177 markers are dropped outright, and the 67
required ones become bold text.
Diffed the normalized v0.3.0 output against v0.2.0 on kagent main's
go/api/v1alpha3: all 67 changed lines are explained purely by the added
marker, with no other difference. So this is the v0.2.0 output plus
required-field marking and nothing else. Verified the normalization
block runs verbatim as the workflow renders it, and that the markers
survive the angle-bracket pass that follows.
Also bumps actions/setup-go from v4 to v5, off deprecated Node 20. Two
other workflows in this repo already run setup-go@v5, so this one was
the last v4. actions/checkout is left alone deliberately: it is 8 call
sites across 6 workflows and belongs in its own change.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
changed the title
This job ran nightly against kagent main, which meant the 1.x reference described code that no released kagent contained, while the install commands on those same pages pinned an older release. That is not hypothetical. The 2026-09-22 run documented KagentHarnessCompaction and KagentHarnessSummarizer, neither of which exists at v1.0.0-alpha1, on pages whose `helm install --version` line says alpha1. The same run moved the Agent Substrate conref to 0.2.0-beta5; alpha1 pins beta4. A reader following those pages would have installed alpha1 and read about a tree they did not have. Changes: - Drops the nightly schedule. The workflow now runs on workflow_dispatch or a repository_dispatch of type kagent-release, and at no other time. A scheduled run can only ask what kagent looks like now, and that answer always drifts ahead of what anyone can install. - Adds a resolve job that picks the release to document -- an explicit version from either dispatch shape, otherwise kagent's latest release -- and validates it: version shape, tag existence, and a refusal to document any 0.x version, since 0.x is frozen at v0.10.1 and a 0.x dispatch would overwrite 1.x content with 0.x values. - Pins both checkouts to release tags. kmcp gets its own latest release rather than anything derived from the kagent tag, since it is unversioned in the docs and released on its own cadence. - Writes versions/kagent.md from the resolved tag. It was editorial because `git describe` on main yields a dev tag, an objection that only held while this ran from main. Leaving it manual now would let the install command drift from the reference pages regenerated beside it. The 1.x span is replaced with the same surgery used for agent-substrate.md, including the assertion that the frozen 0.x span came through byte-identical. - Resolves the runtime image digests at the release tag instead of reading versions/kagent.md. That read was correct only while the conref was updated ahead of the run; now that the same run writes it, reading it here would pin the images one release behind. Verified the rendered conref surgery against the real versions/kagent.md (1.x span moves to 1.0.0-alpha2, 0.x span untouched, no trailing newline gained) and the resolve step against the live GitHub API: it picks v1.0.0-alpha2, and rejects a 0.x version, an absent tag, and a non-version string. The release lives in kagent-dev/kagent, so `on: release` cannot fire in this repo. Until kagent's tag.yaml sends the dispatch, cut a release and then run this workflow from the Actions tab. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
versions/kmcp.md was one file answering two different questions, and it
only looked correct because kagent happened to pin kmcp's newest
release. kmcp 0.4.0 broke the tie -- kagent alpha1 and alpha2 both pin
0.3.0 -- so one value cannot serve both readers any more:
versions/kmcp.md what kagent bundles, from go/go.mod. Read by
the kagent 1.x support matrix, which
describes the release kagent ships. Stays
0.3.0.
versions/kmcp-latest.md kmcp's newest release. Read by the standalone
kmcp quickstart and install guide, both of
which render it inside sample CLI output
reading "No version specified, using latest:
v...". That line is a claim about what kmcp
resolves to, so kagent's pin is wrong there.
Bumping the single conref to 0.4.0 instead would have made the kagent
support matrix claim alpha2 bundles kmcp 0.4.0, which it does not --
the same drift this branch removes for kagent itself.
The cross-check step that used to warn about this divergence now writes
both values and reports the split, since it is deliberate. An unreadable
kmcp release leaves kmcp-latest.md alone rather than blanking it, the
same way an unresolved image digest already does.
Verified with a Hugo build: both kmcp pages render 0.4.0 and the kagent
support matrix still renders 0.3.0. Ran the rendered conref step against
a copy of the real versions/ directory with alpha2 values -- both
version-split files take the new 1.x value with the frozen 0.x span
byte-identical, and no conref gains a trailing newline.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Cut 34 of the 131 comment lines this branch added, against 129 lines of code. The file was already 29% comments before this branch and is 30% now, rather than 32%. What went: a two-column table describing the kmcp split, which restated the two filenames and their values; three header paragraphs about generating from a tag, where one carries the rule and the concrete failure; the "Retargeted from 0.x on 2026-09-11" history, superseded by the tag change; and the restatements in the kagent.md and digest notes. What stayed is the set that stops a specific regression: why there is no schedule, why the digest step no longer reads versions/kagent.md (doing so now would pin images one release behind, silently), why 0.x dispatches are refused, and the crd-ref-docs pin floor. No logic changed. Re-ran the resolve step against the live API and the rendered conref step against a copy of the real versions/ directory to confirm the trim did not disturb either. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Rachael Graham <rachael.graham@solo.io>
Rachael-Graham
marked this pull request as draft
September 22, 2026 17:45
Rachael-Graham
marked this pull request as ready for review
September 22, 2026 21:16
Nadine2016
approved these changes
Sep 22, 2026
Rachael-Graham
changed the title
Rachael-Graham
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The defect
The nightly job generated the 1.x reference from kagent
main, so the docs described code no released kagent contained while the install commands on the same pages named an older release.The 2026-09-22 run is the evidence: it documented
KagentHarnessCompactionandKagentHarnessSummarizeron pages whosehelm install --versionline said alpha1 — a release in which neither type exists. The same run moved the Agent Substrate conref to 0.2.0-beta5, which alpha1 does not pin.It was also failing outright since the runners moved to Go 1.27, which is the first commit here.
What changes
versions/kagent.mdis now written by the job rather than by hand. It was editorial only becausegit describeon main yields a dev tag.crd-ref-docsv0.1.0 → v0.3.0, which fixes the Go 1.27 break and marks required fields. Both generation steps normalize the markers, since v0.3.0 stamps all 244 Validation rows and Hextra renders its escaped braces literally.kmcp.mdis what kagent bundles (0.3.0, for the support matrix),kmcp-latest.mdis kmcp's newest release (0.4.0, for the standalone guides).actions/setup-gov4 → v5, off deprecated Node 20.Verified
Ran the resolve step and the rendered conref step against the live API and a copy of the real
versions/directory. A Hugo build confirms both kmcp pages render 0.4.0 and the kagent support matrix still renders 0.3.0. #502 is what the workflow produced from this branch.Follow-ups, not in this PR
repository_dispatchfrom kagent, which needs a GitHub App. Superseded by Trigger ref docs on a docs release, and generate both 0.x and 1.x #525, which switches to publishing a release in this repo instead — the patternagentgateway/websiteandkgateway-dev/kgateway.devalready use, with no cross-repo credentials.actions/checkout@v4is still on deprecated Node 20 across 8 call sites in 6 workflows.