docs(upgrade-guide): cover Loader entry tree reports and Include journal
This commit is contained in:
1 parent
db1a3b3754
commit
eef0b3e688
3 files changed
+66
No files matched your search
@@ -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
|
||||
@@ -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()`.
|
||||
@@ -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()` 之后运行时编辑已出现在配置文件中。
|
||||
Reference in new issue
Block a user