From eef0b3e688c8edfd9da2ce60c7280637f0cbe5c7 Mon Sep 17 00:00:00 2001 From: Shigma Date: Wed, 28 Oct 2026 19:40:56 +0800 Subject: [PATCH] docs(upgrade-guide): cover Loader entry tree reports and Include journal --- .../cordis-loader-entry-trees/guide.i18n.yaml | 16 ++++++++++++ .../cordis-loader-entry-trees/guide.md | 25 +++++++++++++++++++ .../cordis-loader-entry-trees/guide.zh.md | 25 +++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.i18n.yaml create mode 100644 docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md create mode 100644 docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.i18n.yaml b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.i18n.yaml new file mode 100644 index 0000000000..763bc61176 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.i18n.yaml @@ -0,0 +1,16 @@ +# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md +/: + en: 4b668dd74d0315b9 + zh: a1885d2bbb4ef33e +/loader-entry-tree-reports-and-include-persistence: + en: dc27815908c90cd9 + zh: e9cc077d4d3fdbec +/loader-entry-tree-reports-and-include-persistence/change: + en: 2436912b9554b6dd + zh: ff4582ebc4672662 +/loader-entry-tree-reports-and-include-persistence/migration: + en: cd7db13e17bfd339 + zh: be43c51c78e55439 diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md new file mode 100644 index 0000000000..764cc06772 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.md @@ -0,0 +1,25 @@ +--- +kind: upgrade-guide +description: "Loader entry trees report mutations through commit(change), reject ids containing a colon, and Include persists them through a journal." +--- + +# Loader entry tree reports and Include persistence + +English | [中文](guide.zh.md) + +## Change + +`@deepseek-ai/cordis-plugin-loader` follows Loader 1.0.0-rc.8, and `@deepseek-ai/cordis-plugin-include` follows Include 1.1.1. This affects `cordis.yml` and patch files, code that subclasses `EntryTree`, and code that calls `applyEntryPatches` or relies on Include writes. + +- `EntryTree.write()` is removed. Subclasses implement `commit(change: EntryChange)`, which receives each create, update, move, removal and explicit Fiber save synchronously. In-memory trees implement a no-op. +- An entry `id` containing `:` is rejected, because `:` separates nested tree paths. A configured row such as `id: foo:bar` previously mounted; it is now logged as an error and skipped, and a programmatic `create()` throws. +- `applyEntryPatches(data, patches, warn)` always returns cloned entries, including without patches, and clones inserted rows. Callers can no longer mutate the input through the result. +- Include persists runtime changes through a journal reconciled with the latest file. File edits win conflicting fields and are logged as conflicts. Changes to patch-owned fields and inserted rows update the parent Include's patches. `flush()` waits for pending writes and rejects while changes remain unsaved; `refresh()` and `stop()` return the same result. + +## Migration + +1. Rename entry ids that contain `:` in `cordis.yml`, profile patches and `--patch` overlays, for example `foo:bar` to `foo-bar`, and update patches that address them. +2. In `EntryTree` subclasses, replace `write()` with `commit(change)`. Persist from `change.options` and `change.legacy`: a missing `legacy` is a creation and a missing `options` is a removal. +3. Treat the `applyEntryPatches` result as the only copy to modify. +4. Where code needs a runtime change on disk, await `include.flush()`; for patch-owned changes, flush the child Include and then its parent. +5. Start the application and confirm that no `entry id must not contain ":"` errors are logged and that runtime edits appear in the configuration file after `flush()`. diff --git a/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md new file mode 100644 index 0000000000..74cd3f6ec4 --- /dev/null +++ b/docs/upgrade-guide/v0.2.2-alpha.2/cordis-loader-entry-trees/guide.zh.md @@ -0,0 +1,25 @@ +--- +kind: upgrade-guide +description: "Loader 条目树通过 commit(change) 报告变更并拒绝含冒号的 id,Include 通过 journal 持久化这些变更。" +--- + +# Loader 条目树变更报告与 Include 持久化 + +[English](guide.md) | 中文 + +## 变更 + +`@deepseek-ai/cordis-plugin-loader` 跟随 Loader 1.0.0-rc.8,`@deepseek-ai/cordis-plugin-include` 跟随 Include 1.1.1。受影响的是 `cordis.yml` 与 patch 文件、继承 `EntryTree` 的代码,以及调用 `applyEntryPatches` 或依赖 Include 写盘的代码。 + +- 移除了 `EntryTree.write()`。子类改为实现 `commit(change: EntryChange)`,它会同步收到每一次创建、更新、移动、删除和显式 Fiber 保存。内存树实现为空操作。 +- 含 `:` 的条目 `id` 会被拒绝,因为 `:` 用于分隔嵌套树路径。此前 `id: foo:bar` 这样的配置行可以挂载;现在会记录一条错误并跳过该行,程序化调用 `create()` 会抛出异常。 +- `applyEntryPatches(data, patches, warn)` 总是返回克隆后的条目,没有 patch 时也一样,插入行同样会被克隆。调用方不能再通过结果修改输入。 +- Include 通过与最新文件协调的 journal 持久化运行时变更。文件编辑在字段冲突时优先,并记录为冲突。对 patch 所拥有字段和插入行的修改会写入父 Include 的 patch。`flush()` 等待待处理的写入,并在仍有未保存变更时拒绝;`refresh()` 和 `stop()` 返回相同的结果。 + +## 迁移 + +1. 在 `cordis.yml`、profile patch 和 `--patch` 覆盖层中重命名含 `:` 的条目 id,例如把 `foo:bar` 改为 `foo-bar`,并同步更新引用它们的 patch。 +2. 在 `EntryTree` 子类中把 `write()` 换成 `commit(change)`。根据 `change.options` 和 `change.legacy` 持久化:缺少 `legacy` 表示创建,缺少 `options` 表示删除。 +3. 只修改 `applyEntryPatches` 返回的结果。 +4. 需要运行时变更落盘时,await `include.flush()`;对于 patch 所拥有的变更,先 flush 子 Include,再 flush 其父 Include。 +5. 启动应用,确认没有记录 `entry id must not contain ":"` 错误,并且 `flush()` 之后运行时编辑已出现在配置文件中。