docs(plugin-spec): the migration example no longer teaches the retired onUpgrade hook - #4300
Merged
Merged
Conversation
…d onUpgrade hook The page carries a warn Callout stating the onInstall/onEnable/onDisable/ onUninstall/onUpgrade family never existed and was retired (#4212) — and then, 600 lines down, its CHANGELOG example told the reader "the `onUpgrade` lifecycle hook runs automatically when the package is upgraded to v2.0.0 and renames the field on existing records." A reader who copies the example writes a hook that never runs, which is the exact failure #4212 set out to end. Replaced with the mechanism the same page already documents 320 lines above: upgrade applies metadata migrations (ADR-0087), and no plugin code runs at install/uninstall/upgrade. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
size/xs
documentation
os-zhuang
marked this pull request as ready for review
July 31, 2026 04:51
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.
What
Two lines in
content/docs/protocol/kernel/plugin-spec.mdx. The page carries a warn Callout stating theonInstall/onEnable/onDisable/onUninstall/onUpgradefamily never existed and was retired (#4212) — and then, 600 lines further down, its CHANGELOG example told the reader:A reader who copies that example writes a hook that never runs — the exact failure mode #4212 set out to end. Replaced with the mechanism the same page already documents 320 lines above: upgrade applies metadata migrations (ADR-0087), and no plugin code runs at install/uninstall/upgrade.
Why this is the whole diff
This closes out the docs-accuracy question raised by the drift-check advisory on #4242. The retired surfaces were swept against every hand-written doc first — the 17 never-fired event names from #4241 (
plugin:started,plugin:error,service:registered, …),ObjectQLHostContext,ITypedEventEmitter,PluginLifecycleEventType, andengine.use(— and they appear in exactly one place: the v17 release notes that document them as removed.kernel/events.mdxlists only events in the surviving 14.The
onEnablementions elsewhere were checked against code and are correct — the app-bundleonEnableis a live contract dispatched byAppPlugin.start()(packages/runtime/src/app-plugin.ts:593), and thectx.drivers.register(driver)facadedata-modeling/external-datasources.mdxdocuments is built there too (app-plugin.ts:604). No change needed in those docs.Verification
node scripts/check-doc-authoring.mjs— 214 files clean.Noted, not addressed here
content/docs/kernel/cluster.mdxdescribes a cluster coordinator that wrapsonEnableand releases a lock ononDisable.leader-electedresolves only topackages/spec/src/kernel/cluster.zod.tsand its test — no runtime implementation found. That looks like a separate declared-but-unbuilt surface needing its own ADR-0049 enforce-or-remove pass, not a docs edit.Generated by Claude Code