docs(ui,protocol): 补齐六个此前只被"点过名"的变体 - #4244
Merged
Merged
Conversation
…checked Follow-up to the #4177 variant/doc gate, using the signal it produced. That gate passes a variant if the page contains either `<disc>: '<variant>'` or a bare `` `variant` ``, and its header says plainly that the second form is loose: a pass means the page says the word, not that it documents the thing. Six variants were passing on the loose form alone — the gate's own "weak pass" list, and a precise worklist. apps.mdx enumerated nine navigation item types but only documented six. `report`, `action` and `component` shared one sentence — "the spec also defines …" — while the other six each had a section with an example. They now have their own, and the intro no longer implies a second tier of half-supported types. The `action` section earns its place: `actionName` lives inside a nested `actionDef` block, not at the top level, which is exactly the shape a reader guesses wrong. Both it and `component` note which sub-object stays OPEN by design (`actionDef.params`, `component.params`) — the sibling contract owns those, and after #4165 everything around them is strict. knowledge.mdx had a table naming `object` / `file` / `http` and no example of any, so the per-kind keys (`contentFields` vs `prefix` vs `urls`) appeared nowhere. Added one example each. Every example was parsed against the real schema before committing — NavigationItemSchema and KnowledgeSourceKindSchema, six for six. Writing docs from memory is how the region example in #4218 ended up using an `id` key that does not exist; not repeating that. Anchored-form coverage for these two unions: 9/12 → 12/12. check:variant-docs, check:docs, check-doc-authoring and check:strictness-ledger all green; content/docs/references unchanged. Refs #4001, #4177 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0147tNF4Snk7Ry1KGt4a5PY4
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/s
documentation
Check Changeset failed: the gate wants a changeset on every PR, and its message says how — "an empty changeset is fine for changes that release nothing". I had asserted in the PR description that a docs-only change needs no changeset. That was wrong about this repo's convention: 72 empty changesets already exist, and they are how documentation work records itself without bumping a package. Added one in that form (empty frontmatter, description only). The alternative the message offers — a `skip-changeset` label — would suppress the record instead of writing it, which is the wrong trade for a change that has something worth saying in the release notes. Refs #4001, #4177 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0147tNF4Snk7Ry1KGt4a5PY4
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.
#4177 变体/文档闸门的后续,用的正是它产出的信号。
那道闸门判定一个变体"已记录"的条件是:页面里出现
<判别键>: '<变体>'或出现裸的`变体`。它的头注写得很直白:第二种形态是宽松的,通过只代表页面说了这个词,不代表它记录了这件事。有六个变体正是只靠宽松形态通过的——那就是闸门自己产出的"弱通过"清单,也是一份精确的工作单。
apps.mdx:列举了九种,只记录了六种
report、action、component共享一句话——"the spec also defines …"——而另外六种各有独立小节和示例。现在它们也有了,导言也不再暗示存在"半支持的第二梯队"。action那节尤其值得写:actionName位于嵌套的actionDef块里,不是顶层键——这恰恰是读者最容易猜错的形状。action和component都点明了哪个子对象是刻意开放的(actionDef.params、component.params):那是兄弟契约的地盘,而在 #4165 之后它们周围的一切都已经是 strict。knowledge.mdx:有表格,零示例
原本有一张表点名
object/file/http,但一个示例都没有,于是三种 kind 各自的键(contentFieldsvsprefixvsurls)在文档里根本无处可见。各补了一个示例。每个示例都对着真实 schema 解析过
提交前用
NavigationItemSchema和KnowledgeSourceKindSchema逐个safeParse,六个全过。凭记忆写文档正是 #4218 里那个 region 示例用上不存在的
id键的原因——不重复同一个错误。度量
check:variant-docs、check:docs、check-doc-authoring、check:strictness-ledger全绿;content/docs/references零变动。更正:changeset
这份描述最初写的是「纯文档改动,无 changeset」。那是错的,
Check Changeset随即失败并给出了正解:该闸门要求每个 PR 都有 changeset,而「不发布任何东西的改动用空 changeset 即可」。仓库里已经有 72 个空 changeset——那正是文档类工作在不 bump 任何包的前提下留下记录的方式。已按该形式补上(空 frontmatter + 描述)。
闸门提示的另一个选项
skip-changeset标签被我放弃了:它是压制记录而不是写下记录,对一个在发布说明里确实有话可说的改动来说是错误的取舍。Refs #4001, #4177
🤖 Generated with Claude Code
https://claude.ai/code/session_0147tNF4Snk7Ry1KGt4a5PY4