Skip to content

README.md

Latest commit

 

History

History
130 lines (96 loc) · 6.23 KB

README.md

File metadata and controls

130 lines (96 loc) · 6.23 KB
Raw

台账碎片规范

本目录是本仓已确认缺陷、待实现特性、文档债与 design-gate 的唯一真源：一条目一个碎片文件。 权责边界（哪些字段归本目录、哪些归版本计划和 Proposal）见 规划与交付治理， 阅读入口和维护规则见 台账入口。

为什么是碎片而不是一张大表

和 changelog.d/ 同因同治。旧结构是 docs/backlog.md 里的四张大表，仓规又要求每个实现 MR 更新 自己条目的状态行——于是并行分支各改各的行，却写在同一个文件的相邻行上，三方合并稳定撞成 hunk 冲突。碎片化把「一个条目」变成「一个文件」，独立修改从此落在不同文件里，合并不再产生假冲突； 真正需要冲突的情况（两个 MR 改同一条目）仍然会冲突，这是对的。

同理，本目录不生成一份入库的总表：入库的总表会被每个实现 MR 重新生成，冲突原样回来。 要看全表就按需现渲一份（见下文「渲染与校验」）。

目录

docs/backlog.d/
├── README.md
├── BUG-20260826-01.md
├── DG-050-01.md
└── PB-050-13.md

碎片全部平铺在本目录，不分子目录。种类由编号前缀决定，不写进 frontmatter——身份写在文件名里， 与 changelog.d/ 保持同一惯例。

何时必须写

  • 发现新缺陷：先建碎片登记，再分配 changelog.d 需要的 change-id；
  • 提出新特性或新债务：先建碎片拿到编号，再进版本范围 MR；
  • 需要仓主裁决的设计点：建 DG- 碎片，并在对应条目的指针里引用它。

以下不写碎片：纯文案、纯测试、明确的生成物修复，以及不改变外部行为、也不产生待办的重构。

文件名

docs/backlog.d/<id>.md

文件名必须匹配，且与 frontmatter 的 id 逐字节一致：

^(PB-[0-9]{3}-[0-9]{2}|BUG-[0-9]{8}-[0-9]{2}|DG-[0-9]{3}-[0-9]{2}|DOC-[0-9]{8}-[0-9]{2})\.md$
  • PB-<版本三位>-<序号>：特性 / 已排期工作，例如 PB-050-13；
  • BUG-<YYYYMMDD>-<序号>：未排期缺陷，例如 BUG-20260826-01；
  • DG-<版本三位>-<序号>：design-gate 裁决点，例如 DG-050-07；
  • DOC-<YYYYMMDD>-<序号>：文档债快赢项。

编号一经分配不再改写：CHANGELOG 碎片、Proposal、版本计划和验证报告都按编号互指。

字段

碎片 = 一段 frontmatter（短字段）+ 若干 ## 小节（长文本列）。

前缀 章节 frontmatter 正文小节
PB 特性 id / title / target / status ## 动机、## 备注
BUG 缺陷 id / title / status ## 动机
DG design-gate id / title / target / status ## Proposal
DOC 文档债 id / title ## 动机
  • status（PB / BUG）只用：待排期、待裁决、已排期、实现中、已验证，外加发布收尾专用的 待真机验收——由收尾人在跑 finalize 前标注，release_finalize 据此把条目归进 EVIDENCE_PENDING 档（实现已完成、只差真机/接入方证据，碎片保留不删）。口径见发版清单 第 10 节；日常实现 MR 不用它；
  • status（DG）只用：待裁决、已裁决；
  • target 只用完整 SemVer 或未排期字面量 —；
  • 字段与小节都是封闭集：缺一个判红，多一个也判红。

内容

---
id: PB-050-13
title: CLI 公共 API surface 收口
target: 0.5.0
status: 实现中
---

## 动机

0.4.1 的 canonical CLI library 暴露 203 个符号……

## 备注

[CLI 公共 API 收口](../proposals/0.5.0/cli-public-api-surface.md)（已接受）；DG-050-07 已裁决……

要求：

  • frontmatter 是 key: value 单行字段，值取冒号后的原文，不做 YAML 引号或转义解析；
  • 每个 ## 小节 只能有一行——它渲染成表格的一个单元格。需要展开就写进 Proposal 或验证报告， 在小节里只留指针；这条由 check_planning 机检；
  • 小节里不能出现 |，它会破坏渲染出的表格行；
  • 仓内链接一律相对本目录，即以 ../ 开头（写成 ../proposals/<版本>/<名>.md）；渲染成表格时工具会去掉 这一层，两个方向互为逆运算，机检保证往返等价；
  • 一条一句，动机给证据指针，不粘贴过程，不在状态或备注里重复版本优先级和依赖；
  • 待裁决 的 PB 碎片必须同时引用 Proposal 和 design-gate。

MR 流程

  1. 新条目：建碎片拿编号；范围 MR 同时更新碎片的 target 和对应版本计划。
  2. 实现 MR 只改自己条目的碎片文件。这条独占规则就是消除冲突的机制：不要顺手整理别人的碎片， 不要把多个条目的状态合进一次编辑，也不要重新引入任何形式的入库总表。
  3. 一个碎片由当前推进它的 MR 修改；两个 MR 真的在改同一条目时，合并冲突是正确信号，回到来源分支 谈清楚，不在候选分支拼接。
  4. 延期：清 target 为 —、status 改回 待排期，并保留未满足的证据指针。
  5. 放弃：移入 design.md 的非目标台账 并写理由，然后删除碎片。
  6. 完成：内容进 CHANGELOG 对应版本段；碎片由 release_finalize 在四包实际发布之后删除。

渲染与校验

$ dart run tool/check_planning.dart          # 结构 + 跨文档一致性
$ dart run tool/backlog_render.dart          # 按需渲染只读总表（不要提交）
$ dart run tool/backlog_render.dart --out /tmp/backlog-view.md

check_planning 校验：文件名与 id 一致、必填字段齐全、字段与小节封闭集、状态与目标版本词表、 小节单行且可渲染、仓内链接前缀、Proposal 与 design-gate 指针可解析且被对方声明、目标为当前版本的 条目在版本计划 P0/P1/P2 中恰好出现一次，以及 docs/backlog.md 没有重新长出条目行。

一次性迁移脚本 tool/migrate_backlog.dart 把旧的单文件大表拆成本目录的碎片，并以往返逐字节比对 作为自检；它是幂等的，仍有在途分支改老表时合并后重跑一次即可。