docs: record PR label taxonomy
This commit is contained in:
Tianyi Cui
@@ -0,0 +1,60 @@
|
||||
# Agent Note: 语义化 PR 标签分类体系
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-25-semantic-pr-label-taxonomy.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
PR（Pull Request）需要传达两个不同的信号：它带来哪一类变更，以及会影响仓库中的哪些领域。一套扁平或命名宽泛的标签会混淆这两个问题，掩盖 `session`、`llm` 等不同领域的工作，也让评审人和自动化流程得到的输入缺乏有效信息。
|
||||
|
||||
仓库还会随时间发展出新的领域。如果把当前的领域标签视为封闭集合，未来的工作就只能归入不准确的标签或通用兜底标签。
|
||||
|
||||
## 决策
|
||||
|
||||
每项开放或已合并的 PR 都带有恰好一个类型标签，以及所有受到实质影响的领域标签。未合并即关闭的 PR 不属于持续维护的历史记录集合。其他管理用途的标签可以并存，但都不能满足这两个维度中的任一个。
|
||||
|
||||
### 类型
|
||||
|
||||
| 类型 | 含义 |
|
||||
|---|---|
|
||||
| `feature` | 新增行为或有意改变行为。 |
|
||||
| `bug-fix` | 修正错误行为。 |
|
||||
| `doc` | 仅修改文档。 |
|
||||
| `testing` | 修改测试或测试基础设施，但不改变产品行为。 |
|
||||
| `cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
|
||||
|
||||
类型记录变更的主要意图：配套测试与文档并不会把一项功能或缺陷修复变成测试或文档变更。
|
||||
|
||||
领域记录仓库中的语义领域，而不是临时项目、归属关系或偶然触及的每条路径。如果一项 PR 修改了多个领域，就可以带有多个领域标签。
|
||||
|
||||
### 当前领域
|
||||
|
||||
当前的 43 个领域如下。分组名称仅用于提高列表的可读性；它们既不是标签，也不是分类体系中的另一个层级。
|
||||
|
||||
| 分组 | 领域 |
|
||||
|---|---|
|
||||
| agent（智能体）与模型 | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
|
||||
| 编排 | `subagent`, `workflow`, `planning`, `tasks`, `telemetry`, `storage`, `workspace` |
|
||||
| 能力 | `bash`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `sandbox`, `mcp`, `hooks`, `cordis` |
|
||||
| 接口 | `ui`, `web`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `desktop`, `vscode`, `website` |
|
||||
| 仓库与发布 | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
|
||||
|
||||
### 可扩展性
|
||||
|
||||
领域集合有意保持可扩展。当分类体系缺少一个会反复涉及且具有实际意义的仓库领域时，就新增领域；不要仅为一项 PR、临时项目、状态、个人或团队新增标签。当领域模型发生变化时，重命名、拆分或退役相应领域，同时更新本列表以及所有受影响的开放和已合并 PR。
|
||||
|
||||
类型集合保持精简，因为各类型互斥。新增类型的前提是存在一种当前五类无法表达的独立变更意图；类型不能用来替代领域。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **一套不区分维度的标签。** 不予采纳，因为类型与领域回答的是不同问题；两者混在一起时，存在一个维度的标签并不表示另一个维度也经过了考虑。
|
||||
- **一套固定、封闭的领域集合。** 不予采纳，因为仓库领域会持续演变。封闭集合会以牺牲语义准确性为代价来维持拼写不变。
|
||||
- **一个宽泛的 `core` 领域，或从包（package）结构派生的标签。** 不予采纳，因为 `session`、`llm` 和 `agent` 等领域在跨越包边界时仍各自具有意义，而偶然涉及的文件路径并不是评审人或自动化流程所需的范围信息。
|
||||
- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以合理地跨越多个领域；省略次要领域会隐藏受影响的契约。
|
||||
|
||||
## 后果
|
||||
|
||||
- 评审人和自动化流程获得一个稳定的意图信号，以及完整的语义范围。
|
||||
- 选择标签仍然需要判断：路径和标题前缀可以提示领域，但不能替代阅读变更内容。
|
||||
- 变更分类体系会产生维护工作。新增、重命名、拆分或移除领域时，需要更新本决策记录，并回填开放和已合并的 PR，使历史查询保持原有含义。
|
||||
Reference in New Issue
Block a user