From ea21803acb021f497ed7650a10cd489bf5259822 Mon Sep 17 00:00:00 2001 From: JianFeeeee Date: Sat, 12 Sep 2026 13:05:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(branching):=20=E6=98=8E=E7=A1=AE=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E8=80=85=E6=96=87=E6=A1=A3=E7=9A=84=E5=8F=91=E5=B8=83?= =?UTF-8?q?=E5=BD=92=E5=B1=9E=E2=80=94=E2=80=94=E4=BB=A5=20rel=20=E5=88=86?= =?UTF-8?q?=E6=94=AF=E7=9A=84=E5=BD=A2=E6=80=81=E4=B8=BA=E5=87=86=EF=BC=8C?= =?UTF-8?q?=E5=86=8D=E5=90=88=E5=85=A5=20main?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户裁定：开发者文档应当在每个 rel 分支被修正为对应 rel 的形式，随后合入 main。 新增 §二.7，写清： - 规则与做法（release 上按本版口径改 → cherry-pick 到 main，遵守 §三 只 pick 不 merge） - 为什么不能直接改 main：main 语义是「下一个未发布版本」；assets/docs 会随发行包 分发并在 WebUI 被阅读，服务的是「这一版」；版本号/工具名/机制有无都随版变动 - main 上描述「下一版才有」的行为必须显式标注（如「（下一版）」） - 反例表（本仓真实踩过）：人格卡写死 v0.9.0 + 已删除的 C ABI、架构文档把已移除的 描述式索引/引用计数写成现行、README 停在旧版本 - 配套硬约束：任何会被当作事实的文本不得写死版本号，须插值或读运行时快照并加测试 --- docs/git-branching.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/git-branching.md b/docs/git-branching.md index 563511c..3d6f198 100644 --- a/docs/git-branching.md +++ b/docs/git-branching.md @@ -130,6 +130,45 @@ main ──────────────── E ──────── --- +### 7. 开发者文档的发布归属（以 rel 分支的形态为准） + +**规则：面向使用者的开发者文档，先在对应的 `release/vX.Y.x` 上修正成「这一版的实际行为」， +再 cherry-pick 合入 `main`。**（文档属 §二.3 所列的发布分支允许事项之一） + +为什么不能直接改 main： + +- `main` 的语义是**下一个未发布版本**（§二.1）。在那儿写的文档要么描述尚未发布的行为， + 要么与当前 rel 的实际行为**相反**，而文档的读者（包括模型自身）会把它当事实。 +- `assets/docs/**` 会**随发行包分发并在 WebUI 里被阅读**——它服务的是“这一版”，不是“下一版”。 +- 版本号、工具名、机制的有无都是**随版变动的**：同一个文件在两个分支上就应该是两种口径。 + +做法： + +```bash +git switch release/v1.2.x +# 按这一版口径修改：版本号、当前工具名（hmapdev）、已移除机制不再写成现行 +# ... 编辑 assets/docs/**、README{,_EN}.md、docs/zh/** ... +git commit -m "docs: 按 v1.2.x 口径修正 …" +git switch main && git cherry-pick # 遵守 §三：只 pick，不 merge +``` + +`main` 上若需要描述“下一版才有的行为”，必须显式标注（如「（下一版）」或附版本号）， +不得让读者以为它已发布。 + +**反例（本仓真实踩过，均为“文档当成事实后反向误导”）**： + +| 现象 | 后果 | +|---|---| +| 人格卡写死 `v0.9.0（C ABI v2）` | 内核接口/日志报 1.2.0，agent 却向用户自述旧版本（且该机制 v1.0.0 已删除） | +| 架构文档在 1.2.0 后仍把“描述式索引 + 引用计数 GC”写成现行机制 | 读者按已删除的设计理解现行行为 | +| README 停在 v1.1.1 并描述已被删除的机制 | 同上 | + +配套硬约束：**任何“模型或用户会当作事实”的文本，都不得写死版本号**—— +要么用 `meta.Version` 插值，要么要求读运行时快照，并用测试钉住 +（如 `TestDefaultPersonaPromptHasNoVersionLiterals`）。 + +--- + ## 三、当前分支对齐（2026-09-12 更新） ### 主仓（TrueAgent）