docs: implementation-accuracy pass — retire deprecated titleFormat example + evidence-backed doc fixes#2640
Merged
Merged
Conversation
…evidence-backed doc fixes Recheck of the hand-written docs against the actual implementation. Two parts: 1. Deprecated-key sweep (all 146 hand-written docs). The concrete report was `titleFormat` still shown as current usage though it is deprecated ([DEPRECATED → nameField (ADR-0079)] in packages/spec/src/data/object.zod.ts). The live example in data-modeling/formulas.mdx now uses the sanctioned migration — a text `Field.formula` designated via `nameField` — instead of `titleFormat`. Verified the rest of the deprecated authorable-key class is already correct: reference-table rows for titleFormat/displayNameField/ compactLayout/conditionalRequired/defaultExpanded are marked deprecated with their replacements; view form-section `collapsible`/`collapsed` are the current schema (view.zod.ts FormSectionSchema), not the retired object fieldGroup pair; every `namespace:` hit is `manifest.namespace` (a current required field), not the removed ObjectSchema key. 2. Per-doc accuracy fixes across 40 further docs (client SDK, REST/wire format, automation, seed data, deployment, concepts, …). Highlights: client.connect() resolves with the discovery manifest (not client.discovery); auth login takes email; workflow namespace exposes 3 methods; webhooks docs no longer advertise signed-by-default or SSRF egress guards that are not shipped yet; seed `replace` mode inserts without deleting. Every change is backed by the cited implementation; frontmatter, code fences, and JSX components verified intact. Scoped pass: covers the reported deprecated-key issue across the whole corpus plus deep fixes on the docs reached this round; a full per-doc deep audit of the remaining files is follow-up. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHQscZJ8NvXceSmsPNdTZd
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
added
the
skip-changeset
Claude
os-zhuang
marked this pull request as ready for review
July 5, 2026 16:17
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.
背景
复核报告:
titleFormat早已作废,却仍出现在文档中。核对实现——titleFormat在packages/spec/src/data/object.zod.ts:596标记为[DEPRECATED → nameField (ADR-0079)],但data-modeling/formulas.mdx仍把它当作现行写法示范。本 PR 修正该问题,并附带一轮更大范围的实现一致性修复。改动内容
1. 废弃 key 全量扫描(覆盖全部 146 篇手写文档)
以 spec 为准,对"已废弃/已移除的可写 key"做确定性扫描:
formulas.mdx:把活示例里的titleFormat: tmpl\...`迁移为 ADR-0079 规定的复合标题路径——一个returnType: 'text'的Field.formula,再用nameField指定它。(string()为已注册 CEL 内置函数;returnType: 'text'的 formula 字段是 title-eligible,见display-name.test.ts:45`。)titleFormat/displayNameField/compactLayout/conditionalRequired/defaultExpanded在参考表里均已标注 deprecated 并给出替代项;sections的collapsible/collapsed是现行 schema(view.zod.tsFormSectionSchema),不是已废的对象fieldGroup布尔对,保持不动;namespace:命中都是manifest.namespace(现行必填字段,对象名前缀),不是被移除的 ObjectSchema 键;north-star.mdx的namespace/tableName是"不要重新引入"的护栏,forms.mdx的defaultDetailForm是"已移除"说明——均正确。2. 逐篇实现一致性修复(另外 40 篇)
覆盖 client SDK、REST/wire format、automation、seed data、deployment、concepts 等。重点:
client.connect()返回 discovery manifest(不是client.discovery);auth 登录用email;workflow命名空间为 3 个方法;replace模式语义纠正(loader 本身不删除记录,只插入)。每处改动均以引用到的实现为据;所有改动文件的 frontmatter、代码围栏、JSX 组件均已校验完好。
覆盖范围说明
这是一轮有范围的复核:覆盖了报告问题(废弃 key)在全语料的排查,加上本轮触及文档的深度修复。剩余文档的逐篇深度审计留作后续。
验证
formulas.mdx迁移写法逐项对照 spec / 测试确认。🤖 Generated with Claude Code
https://claude.ai/code/session_01LHQscZJ8NvXceSmsPNdTZd
Generated by Claude Code