docs(releases): curate the v17 platform release page and wire it into the nav - #3906
Merged
Conversation
… the nav Layer 3 of the release history (docs/releases-maintenance.md) is a hand-curated page per major, and v17 had none. The train carries 302 pending changesets — 45 of them marked breaking — so the page that third parties actually read to plan an upgrade was the one artifact the release could not generate. Adds content/docs/releases/v17.mdx, sourced from the pending changesets for the backend and from the four bundled @objectstack/console refresh entries for the frontend. It leads with breaking changes + migration (Node 22 floor, the opt-in export axis, the ApiMethod shrink and its reporter codemod, user-less flow runs refused, the three retired authorable aliases, agent.tools[], approval-request participant visibility, sharing full/group, membership grade, better-auth 1.7 account identity, the deleted SDK surface, the GraphQL removal, the ObjectStackProtocol alias, datasource fail-fast, per-tenant unique, the i18n contract fixes and the dead-spec-cluster prune), then new capabilities (ADR-0104 files-as-records, dynamic approver routing, the reconciled SDK surface, write observability, analytics correctness), a Console (Studio) section, an upgrade checklist and a reference index. Wires "v17" into content/docs/releases/meta.json so the page is navigable, and adds its entry to the releases index — the two things check-release-notes will demand the moment 17.0.0 lands in the spec CHANGELOG. Also corrects the plugin manifest compatibility example in content/docs/protocol/kernel/plugin-spec.mdx: it showed keys PluginManifest does not declare (objectstack / node rather than minObjectStackVersion / maxObjectStackVersion / nodeVersion) alongside a >=18.0.0 Node floor and a >=2.0.0 <3.0.0 platform range, so the one copy-pasteable manifest example in the protocol docs taught a shape the parser strips. #3825 restated the Node prerequisite in ten user-facing places and missed this one. The release page's two remaining uses of the reserved word "role" are the literal sys_member.role column the ADR-0108 section is about; ratcheted into scripts/role-word-baseline.json accordingly. Verified: pnpm docs:build passes (411 doc routes, /en/docs/releases/v17 among them), and check:release-notes, check:doc-authoring, check:role-word, check:org-identifier, check:nul-bytes, check:node-version are green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 29, 2026 00:43
os-zhuang
pushed a commit
that referenced
this pull request
Jul 29, 2026
…tore, first docs sweep Three related closures on the just-merged v17 release page (#3906): 1. The Console section was missing 25 objectui commits. The v17 frontend window is cf2d56e32a11 → 4a4829d0ef39 = 128 commits, but the pending console-*.md changesets covered only 103: the range 2cb8d78e24ad...c6cfdf1288b6 landed with no changeset — exactly the "SHA bump leaves no trace" failure scripts/bump-objectui.sh exists to prevent. Two of the missing commits are breaking and each is the frontend half of a backend change the page already documented (useClientNotifications delegates ↔ #3612 SDK removal; @object-ui/types Capabilities re-exports ↔ the retired capabilities cluster). Both now sit beside their backend halves and in the upgrade checklist, with the other eight substantive commits folded into the Console section and .changeset/console-c6cfdf1288b6-backfill.md recording the range itself. 2. "releases" returns to the root sidebar. #3423 unlisted References and Releases together ("lookup content ... the docs home page links both"); that trade holds for References (22 generated pages) but not for Releases in a release window, when the upgrade notes are what people open the docs for. References stays out. check-release-notes now enforces what its success line already claimed: the section must be reachable via the root nav OR a /docs/releases link on the docs home — either satisfies it (preserving #3423's option), losing both fails the build. Negative-tested both directions. 3. First v17 docs sweep (docs/v17-docs-sweep.md — playbook + append-only run log with a watermark, built to re-run while the RC train iterates). Run 1 fixed the drift v17 left in hand-written prose: services-checklist (17→16 services, graphql rows, the dissolved ObjectStackProtocol), the anonymous-deny matrix still listing /graphql + handleGraphQL, sharing docs describing owner/group shapes as "declared but not enforced" (they no longer parse), http-protocol claiming enable.trash exists, REST/GraphQL in objectql diagrams/prose, and the objectstack-api skill description (mirrors regenerated via gen:skill-docs). False positives and out-of-scope findings (spec comment drift, implementation-status.mdx staleness) are logged for the next run. Verified: pnpm docs:build passes; check:release-notes / doc-authoring / role-word / org-identifier / nul-bytes / skill-docs-sync all green; the new guard branch fails when both entry points are removed and passes with either. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH
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.
为什么
docs/releases-maintenance.md把发布历史分成三层，第三层(content/docs/releases/vN.mdx)是每个 major 必须手写的那一层 —— 迁移指引没法生成。v17 还没有这一页。这趟车目前累积了 302 个 pending changeset,其中 45 个带
!破坏性标记、18 个声明majorbump。v17-rc-anchor已经把它锚定为17.0.0(RC 周期,pre-mode 下发17.0.0-rc.N)。也就是说:第三方开发者规划升级时唯一会去读的那份文档,恰恰是发布流水线唯一生成不出来的产物。改了什么
新增
content/docs/releases/v17.mdx—— 后端内容取自 pending changesets,前端内容取自本次打包的四条@objectstack/consolerefresh 记录(终点 pin4a4829d0ef39)。结构沿用 v16 页:allowExport改为 opt-in、ApiMethod收缩到六个原语(附 reporter codemod 与 legacy-only 白名单会 strip 成 deny-all 的坑)、无触发用户的流程运行拒绝碰数据、最后三个 authorable 别名退役、agent.tools[]移除、审批请求改为参与者可见、sharingfull/group、membership grade 不再是能力通道、better-auth 1.7 账号身份重构与 issuer 回填、SDK 死表面删除、GraphQL 移除、ObjectStackProtocol别名解散、datasource 连不上即 fail boot、unique按租户物化、i18n 契约修复,以及一批 dead spec cluster 的清理表os migrate files-to-references+OS_DATA_VALUE_SHAPE_STRICT_ENABLED的 warn-first 顺序)、审批动态路由(expressionapprover /onEmptyApprovers/ decision outputs)、SDK 与真实路由对齐(route ledger 双向守卫)、写入可观测性(droppedFields)、analytics 正确性、lint 与 CLImeta.json+index.mdx:把v17接进导航和版本列表 —— 这正是check-release-notes在 17.0.0 进入 spec CHANGELOG 那一刻会要求的两件事。顺手修
content/docs/protocol/kernel/plugin-spec.mdx:protocol 文档里唯一可复制的 plugin manifest 例子写的是compatibility: { objectstack: '>=2.0.0 <3.0.0', node: '>=18.0.0' },而PluginManifestSchema声明的是minObjectStackVersion/maxObjectStackVersion/nodeVersion—— 键名对不上会被 parse 静默 strip(PD #12 的典型形状),版本号也是两处过期。#3825 把 "Node 18+" 在十处用户可见位置改成了 22,漏了这一处。验证
pnpm docs:build通过(411 条 doc route,/en/docs/releases/v17已生成.html/.rsc)check:release-notes/check:doc-authoring/check:org-identifier/check:nul-bytes/check:node-version全绿check:role-word:页面里只剩 2 处role,都是 ADR-0108 那节在讲的字面列名sys_member.role;其余表述已改写。按 guard 说明 ratchet 进scripts/role-word-baseline.json(与 v13/v14/v16 页同样处理){}或<tag>说明
.changeset/v17-release-page.md),不发任何包docs/protocol-upgrade-guide.md和packages/spec/spec-changes.json是 ADR-0087 D4 生成物,PROTOCOL_VERSION由scripts/sync-protocol-version.mjs在pnpm version时同步 —— 本 PR 刻意不碰,它们会在发布流水线里随 major bump 一起重新生成。protocol-17 的 conversion 步骤已在conversions/registry.ts里注册好CHANGELOG.md/RELEASE_NOTES.md按 maintenance 文档已被三层结构取代,未改动changeset pre exit之后若最终版本号或内容有出入,这页需要跟一次🤖 Generated with Claude Code
https://claude.ai/code/session_01LXvaYR7TiJBCxYwjn51owH
Generated by Claude Code