From 04ec8cef0cc95a7c82bbfcc75242044e73aa9e8b Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 31 Jul 2026 04:42:44 +0000 Subject: [PATCH] docs(plugin-spec): the migration example no longer teaches the retired onUpgrade hook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh --- .changeset/docs-plugin-spec-onupgrade-example.md | 5 +++++ content/docs/protocol/kernel/plugin-spec.mdx | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 .changeset/docs-plugin-spec-onupgrade-example.md diff --git a/.changeset/docs-plugin-spec-onupgrade-example.md b/.changeset/docs-plugin-spec-onupgrade-example.md new file mode 100644 index 0000000000..54dab453c9 --- /dev/null +++ b/.changeset/docs-plugin-spec-onupgrade-example.md @@ -0,0 +1,5 @@ +--- +--- + +docs: fix the plugin-spec CHANGELOG example that still taught the retired +`onUpgrade` hook as running automatically (#4212 family). Releases nothing. diff --git a/content/docs/protocol/kernel/plugin-spec.mdx b/content/docs/protocol/kernel/plugin-spec.mdx index 9fe567b07a..1c420e7d3b 100644 --- a/content/docs/protocol/kernel/plugin-spec.mdx +++ b/content/docs/protocol/kernel/plugin-spec.mdx @@ -859,8 +859,8 @@ Always include migration guide in CHANGELOG.md for major versions. - `account.owner` field (use `account.owner_id` instead) ### Migration -The `onUpgrade` lifecycle hook runs automatically when the package is upgraded -to v2.0.0 and renames the field on existing records. +Upgrading to v2.0.0 applies the metadata migration that renames the field on +existing records (ADR-0087). No plugin code runs at upgrade. ``` ### 3. Pin Core Dependencies