Merge pull request #1978 from deepseek-harness/worktree/unify-github-label-taxonomy
cleanup: unify GitHub label taxonomy
This commit is contained in:
Tianyi Cui
GitHub
@@ -1,71 +0,0 @@
|
||||
# Agent Note: Semantic pull request label taxonomy
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-25-semantic-pr-label-taxonomy.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Pull requests need two different signals: what kind of change they make and which repository domains they affect. A flat or broadly named label set conflates those questions, hides work in distinct areas such as `session` and `llm`, and gives reviewers and automation weak inputs.
|
||||
|
||||
The repository also gains new domains over time. Treating today's area labels as a closed set would force future work into inaccurate labels or a generic catch-all.
|
||||
|
||||
## Decision
|
||||
|
||||
Every open or merged pull request carries exactly one kind and every materially affected area. Closed pull requests that were never merged are outside the maintained historical corpus. Other operational labels may coexist, but they do not satisfy either dimension.
|
||||
|
||||
### Kinds
|
||||
|
||||
| Kind | Meaning |
|
||||
|---|---|
|
||||
| `feature` | Adds or intentionally changes behavior. |
|
||||
| `bug-fix` | Corrects incorrect behavior. |
|
||||
| `doc` | Makes documentation the dominant intent. |
|
||||
| `testing` | Changes tests or testing infrastructure without changing product behavior. |
|
||||
| `cleanup` | Preserves behavior while maintaining or simplifying the implementation or repository process. |
|
||||
|
||||
The kind records the change's dominant intent: accompanying tests and documentation do not turn a feature or bug fix into a testing or documentation change.
|
||||
|
||||
Areas record semantic repository domains rather than temporary initiatives, ownership, or every path touched incidentally. Area labels are not a hierarchy: a pull request may carry several when it changes distinct contracts, but an umbrella and a narrower label do not both describe the same work.
|
||||
|
||||
### Current areas
|
||||
|
||||
The 46 current areas are listed below. The group names organize the list for readability; they are not labels or another taxonomy level.
|
||||
|
||||
| Group | Areas |
|
||||
|---|---|
|
||||
| Agent and model | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
|
||||
| Orchestration | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
|
||||
| Capabilities | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
|
||||
| Interfaces | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
|
||||
| Repository and release | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
|
||||
|
||||
`gui` covers browser and Electron graphical applications, including standalone graphical developer tools; `vscode` remains the editor extension integration. `ui` covers shared cross-interface commands, approval interaction, presentation, and app boot; it coexists with `gui`, `tui`, or a protocol area only when the pull request also changes that shared contract.
|
||||
|
||||
`tasks` owns background work tied to a running process, while `schedule` owns durable time-triggered jobs. `tools` owns generic registry, schema, and execution contracts; a concrete capability receives `tools` only when it changes one of those contracts. `attachment` owns durable media references and multimodal input delivery, while `artifact` owns model-declared deliverable identity and preview lifecycle; neither borrows `tools` or `ui` for its implementation parts.
|
||||
|
||||
Names follow semantic ownership rather than lexical resemblance. `hooks` means the Claude Code and Codex agent bridges, not local Git hooks; `platform` means product portability, not CI runner selection; and `build` means compilation, bundling, and built package artifacts, not documentation generators.
|
||||
|
||||
### Extensibility
|
||||
|
||||
The area set is intentionally extensible. Add an area when a recurring, meaningful repository domain is missing; do not add a label for one pull request, a temporary project, a status, or a person or team. Rename, split, or retire an area when the domain model changes, and update this list and the affected open and merged pull requests together.
|
||||
|
||||
The kind set stays narrow because kinds are mutually exclusive. A new kind requires a distinct change intent that cannot be represented by the current five; it is not a substitute for an area.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **One undifferentiated label set.** Rejected because kind and area answer different questions; mixing them makes the presence of one label say nothing about whether the other dimension was considered.
|
||||
- **A fixed, closed area set.** Rejected because repository domains evolve. A closed set would preserve spelling at the cost of semantic accuracy.
|
||||
- **One broad `core` area or package-derived labels.** Rejected because domains such as `session`, `llm`, and `agent` remain independently meaningful across package boundaries, while incidental file paths are not the scope reviewers or automation need.
|
||||
- **Separate browser and desktop areas.** Rejected because browser delivery and Electron packaging expose one graphical client domain; splitting them classifies the delivery shell rather than the semantic work.
|
||||
- **Broad implementation areas in place of a domain.** Rejected because a durable scheduled job is not a background task, an attachment is not merely its source interface or filesystem implementation, and an artifact is not merely its declaring tool or preview interface.
|
||||
- **Umbrella and leaf areas for the same contract.** Rejected because duplicate labels inflate scope without adding information. Multiple areas remain correct when a pull request changes genuinely distinct contracts.
|
||||
- **Exactly one area per pull request.** Rejected because coherent changes can legitimately span several domains, and dropping secondary areas hides affected contracts.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Reviewers and automation receive one stable intent signal plus a complete semantic scope.
|
||||
- `gui` queries cover browser and desktop delivery together, while `ui` queries retain only shared cross-interface contracts.
|
||||
- `schedule`, `attachment`, and `artifact` queries identify those domains directly instead of approximating them through implementation dependencies.
|
||||
- Selecting labels remains a judgment call: paths and title prefixes can suggest areas, but they cannot replace reading the change.
|
||||
- Taxonomy changes carry maintenance work. Area additions, renames, splits, and removals update this decision record and backfill open and merged pull requests so historical queries keep their meaning.
|
||||
@@ -1,71 +0,0 @@
|
||||
# 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 修改不同契约时可以带有多个领域标签，但不能用一个总括标签和一个较窄标签重复描述同一项工作。
|
||||
|
||||
### 当前领域
|
||||
|
||||
当前的 46 个领域如下。分组名称仅用于提高列表的可读性；它们既不是标签，也不是分类体系中的另一个层级。
|
||||
|
||||
| 分组 | 领域 |
|
||||
|---|---|
|
||||
| agent（智能体）与模型 | `agent`, `agent-loop`, `session`, `llm`, `model-context`, `compaction`, `tools`, `persistence` |
|
||||
| 编排 | `subagent`, `workflow`, `planning`, `tasks`, `schedule`, `telemetry`, `storage`, `workspace` |
|
||||
| 能力 | `bash`, `subprocess`, `pty`, `filesystem`, `lsp`, `skills`, `web-search`, `code-mode`, `artifact`, `attachment`, `sandbox`, `mcp`, `hooks`, `cordis` |
|
||||
| 接口 | `ui`, `gui`, `tui`, `acp`, `json-rpc`, `cli`, `python-sdk`, `vscode`, `website` |
|
||||
| 仓库与发布 | `dev-infra`, `ci`, `build`, `dependencies`, `platform`, `i18n`, `release` |
|
||||
|
||||
`gui` 涵盖浏览器和 Electron 图形应用，包括独立的图形化开发者工具；`vscode` 仍表示编辑器扩展集成。`ui` 涵盖共享的跨接口命令、审批交互、呈现和应用启动；只有当 PR 还修改这项共享契约时，它才与 `gui`、`tui` 或某个协议领域并用。
|
||||
|
||||
`tasks` 负责与运行中进程绑定的后台工作，`schedule` 则负责持久化的定时作业。`tools` 负责通用的注册表契约、schema 契约和执行契约；具体能力只有在修改其中一项契约时才带有 `tools`。`attachment` 负责持久化的媒体引用和多模态输入传递，`artifact` 则负责模型声明的交付物标识和预览生命周期；二者都不会因实现包含工具或界面部分而借用 `tools` 或 `ui`。
|
||||
|
||||
标签名称以语义归属为准，而不是词面相似性。`hooks` 指 Claude Code 和 Codex 的 agent 桥接，而不是本地 Git 钩子；`platform` 指产品可移植性，而不是 CI 运行器选择；`build` 指编译、打包和已构建的包产物，而不是文档生成器。
|
||||
|
||||
### 可扩展性
|
||||
|
||||
领域集合有意保持可扩展。当分类体系缺少一个会反复涉及且具有实际意义的仓库领域时，就新增领域；不要仅为一项 PR、临时项目、状态、个人或团队新增标签。当领域模型发生变化时，重命名、拆分或退役相应领域，同时更新本列表以及所有受影响的开放和已合并 PR。
|
||||
|
||||
类型集合保持精简，因为各类型互斥。新增类型的前提是存在一种当前五类无法表达的独立变更意图；类型不能用来替代领域。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **一套不区分维度的标签。** 不予采纳，因为类型与领域回答的是不同问题；两者混在一起时，存在一个维度的标签并不表示另一个维度也经过了考虑。
|
||||
- **一套固定、封闭的领域集合。** 不予采纳，因为仓库领域会持续演变。封闭集合会以牺牲语义准确性为代价来维持拼写不变。
|
||||
- **一个宽泛的 `core` 领域，或从包结构派生的标签。** 不予采纳，因为 `session`、`llm` 和 `agent` 等领域在跨越包边界时仍各自具有意义，而偶然涉及的文件路径并不是评审人或自动化流程所需的范围信息。
|
||||
- **为浏览器和桌面端分别设置领域。** 不予采纳，因为浏览器交付和 Electron 打包共同呈现同一个图形客户端领域；拆开二者将按交付形态而非工作的语义进行分类。
|
||||
- **以宽泛的实现领域替代语义领域。** 不予采纳，因为持久化的定时作业不是后台任务，附件不只是其来源接口或文件系统实现，产物也不只是声明它的工具或预览接口。
|
||||
- **同一项契约同时使用总括领域与细分领域。** 不予采纳，因为重复标签只会虚增范围，不会增加信息。一项 PR 确实修改不同契约时，多个领域标签仍然合理。
|
||||
- **每项 PR 恰好一个领域。** 不予采纳，因为一项内聚的变更可以合理地跨越多个领域；省略次要领域会隐藏受影响的契约。
|
||||
|
||||
## 后果
|
||||
|
||||
- 评审人和自动化流程获得一个稳定的意图信号，以及完整的语义范围。
|
||||
- `gui` 查询会同时覆盖浏览器与桌面端交付，`ui` 查询则只涵盖共享的跨接口契约。
|
||||
- `schedule`、`attachment` 与 `artifact` 查询直接对应各自领域，无需通过实现依赖近似归类。
|
||||
- 选择标签仍然需要判断：路径和标题前缀可以提示领域，但不能替代阅读变更内容。
|
||||
- 变更分类体系会产生维护工作。新增、重命名、拆分或移除领域时，需要更新本决策记录，并回填开放和已合并的 PR，使历史查询保持原有含义。
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-27-dependabot-version-updates.md
|
||||
2026-07-27-dependabot-version-updates.md: 5d42563788d9f1e72da65c8e9750d6b1ecba06a5
|
||||
2026-07-27-dependabot-version-updates.zh.md: 4847059944e7e35de5719a6cbfd3d5b133467ccb
|
||||
2026-07-27-dependabot-version-updates.md: bba83c9e720cf87f91638131d7f9580422ea7f76
|
||||
2026-07-27-dependabot-version-updates.zh.md: 74b399778fdd06cbbe38234f7bddc5c28c4fd600
|
||||
@@ -12,7 +12,7 @@ Maintained registry and GitHub Actions dependencies need a regular update path.
|
||||
|
||||
The default branch carries [`.github/dependabot.yml`](../../../../.github/dependabot.yml) with weekly version-update checks for the root pnpm workspace, including `native/landlock-run`, the `python/sdk` uv project, and GitHub Actions. Every entry sets `cooldown.default-days` to `30`, so a version release becomes eligible only after it is at least 30 days old and is proposed on the next weekly check. The [in-repository Landlock release decision](2026-08-06-in-repository-landlock-release.md) owns the shared-workspace boundary.
|
||||
|
||||
The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `cleanup` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
|
||||
The root pnpm version-update scan excludes `vendor/**`, whose source and manifests move only through the [vendoring procedure](../../../../vendor/README.md). GitHub applies `exclude-paths` only to version updates; a security pull request that touches a vendored manifest is replaced through the vendoring procedure instead of being merged as generated. Dependabot pull requests receive the repository's `kind/dependency` kind and `area/infra` area labels, run the normal pull-request checks, and remain subject to maintainer review; this automation does not merge them.
|
||||
|
||||
Repository settings enable dependency vulnerability alerts and Dependabot security updates. GitHub does not apply version-update cooldowns to those security updates, so security fixes remain eligible immediately. A generated pnpm security pull request can still fail the repository's lockfile release-age verification when dependency resolution selects unrelated fresh transitive versions; that pull request waits or is narrowed instead of weakening the policy. The repository's coordinated fresh-release exceptions are not copied into Dependabot's cooldown exclusions: automated version updates use the uniform 30-day wait, while an explicitly reviewed manual update can still follow its owning release procedure.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Status: implemented
|
||||
|
||||
默认分支包含 [`.github/dependabot.yml`](../../../../.github/dependabot.yml)，其中为包含 `native/landlock-run` 的根 pnpm 工作区、`python/sdk` uv 项目和 GitHub Actions 配置了每周一次的版本更新检查。每个更新项都将 `cooldown.default-days` 设为 `30`，因此某个版本只有在发布至少 30 天后才符合更新条件，并会在下一次每周检查时生成更新提案。[仓库内 Landlock 发布决策](2026-08-06-in-repository-landlock-release.md)负责共享工作区边界。
|
||||
|
||||
根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `cleanup` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
|
||||
根 pnpm 工作区的版本更新扫描排除 `vendor/**`，其中的源码和 manifest（元数据清单）只能通过 [vendoring 流程](../../../../vendor/README.md)变更。GitHub 仅将 `exclude-paths` 用于版本更新；如果安全更新 PR（Pull Request）涉及随源码纳入仓库的 manifest，则改由 vendoring 流程处理，以替代自动生成的 PR，而不会将其原样合并。Dependabot PR 会获得仓库的 `kind/dependency` 类型标签和 `area/infra` 区域标签，运行常规 PR 检查，并且仍须由维护者评审；该自动化不会合并这些 PR。
|
||||
|
||||
仓库设置已启用依赖项漏洞警报和 Dependabot 安全更新。GitHub 不会对这些安全更新应用版本更新冷却期，因此安全修复仍可立即进入更新流程。如果依赖解析还选中了其他刚发布的传递依赖，pnpm 安全更新 PR 仍可能无法通过仓库的锁文件发布时长校验；此类 PR 应等待隔离期结束或缩小更新范围，不得因此放宽政策。仓库为协调刚发布版本而设置的例外，不会纳入 Dependabot 的冷却期排除项：自动版本更新统一等待 30 天；经过明确评审的手动更新仍可遵循相应的发布流程。
|
||||
|
||||
|
||||
+3
-3
@@ -1,6 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md
|
||||
2026-07-25-semantic-pr-label-taxonomy.md: 3217b405e968d4d2c1eba1f1a5a08008b18ba514
|
||||
2026-07-25-semantic-pr-label-taxonomy.zh.md: 978f11af9402f248679e2087ff7fb513321b69b9
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md
|
||||
2026-08-08-unified-github-label-taxonomy.md: fddda6c99053e55d3e31a2f6e5c55add09772117
|
||||
2026-08-08-unified-github-label-taxonomy.zh.md: c8d727c9a56d6c7c25f73eacde42e0bef1c779b7
|
||||
@@ -0,0 +1,72 @@
|
||||
# Agent Note: Unified GitHub label taxonomy
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-08-unified-github-label-taxonomy.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Pull request labels answer two independent questions: what kind of change the work makes and which durable repository domains it materially affects. Mixing those dimensions or retaining synonymous plain and namespaced labels makes queries ambiguous, while a closed area inventory forces new domains into inaccurate categories.
|
||||
|
||||
Issues already have a native Type and a separate source taxonomy. Reusing pull request kind or source labels across both object types duplicates metadata and weakens the meaning of each family.
|
||||
|
||||
## Decision
|
||||
|
||||
Every open or merged pull request carries exactly one canonical `kind/*` label and at least one materially affected `area/*` label. Closed pull requests that were never merged retain migrated historical assignments but do not receive invented missing classification. Operational labels may coexist without satisfying either dimension.
|
||||
|
||||
### Kinds
|
||||
|
||||
The kind set is closed and mutually exclusive:
|
||||
|
||||
| Kind | Meaning |
|
||||
|---|---|
|
||||
| `kind/feature` | Adds or intentionally changes behavior. |
|
||||
| `kind/bug-fix` | Corrects incorrect behavior. |
|
||||
| `kind/doc` | Makes documentation the dominant intent. |
|
||||
| `kind/testing` | Changes tests or testing infrastructure without changing product behavior. |
|
||||
| `kind/cleanup` | Preserves behavior while maintaining or simplifying implementation or repository process. |
|
||||
| `kind/dependency` | Updates dependencies without another dominant intent. |
|
||||
|
||||
The kind records the dominant intent. Accompanying tests, documentation, cleanup, or dependency movement do not override a feature or bug fix. A new kind changes this classification contract and requires an explicit taxonomy and policy change.
|
||||
|
||||
Repository policy rejects unsupported `kind/*` values and reserves every alias removed by the unification: `kind/bug`, `kind/documentation`, `feature`, `bug-fix`, `doc`, `cleanup`, `testing`, `dependencies`, `ci`, `cli`, `llm`, and `web-search`. Reserving the exact migrated set prevents an obsolete synonym from being recreated as an apparently unrelated operational label.
|
||||
|
||||
### Areas
|
||||
|
||||
Areas name durable semantic domains rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct contracts, but it does not combine an umbrella and a narrower label for the same contract. GitHub's live `area/*` names and descriptions own the current inventory; this record owns the selection rule and the non-obvious boundaries that cannot fit reliably in short label descriptions.
|
||||
|
||||
- `area/web` covers browser and Electron graphical interfaces, `area/vscode` covers the editor extension, and `area/api` covers cross-interface protocols and language SDKs.
|
||||
- `area/planning` covers goals, plans, todos, and scheduling, while `area/workflow` covers executable workflows and background task runtimes.
|
||||
- `area/artifact` deliberately combines artifacts, attachments, and multimodal delivery. Split labels become justified only when those concerns again need independent review or queries.
|
||||
- `area/tools` applies to generic registry, schema, and execution contracts. A concrete capability uses its own area unless it also changes that generic contract.
|
||||
- `area/hooks` means the Claude Code and Codex bridges, `area/infra` covers build, release, CI, repository gates, generators, dependencies, and developer tooling, and `area/windows` covers native Windows product support rather than CI runner selection.
|
||||
|
||||
The area set is intentionally extensible. When no existing description honestly covers a durable and reusable domain, an agent may create a concise `area/<lowercase-kebab-case>` label without separate approval. It must not create an area for one pull request, an incidental path, a temporary project, a status, or a person or team, and it reports the new label and rationale to the requester after applying it. Reusing an inaccurate area merely to avoid a justified addition is not acceptable.
|
||||
|
||||
### Issues and migrations
|
||||
|
||||
Issues use native Issue Type instead of `kind/*`; their `area/*` labels remain optional. `source/*` labels record Issue provenance and do not apply to pull requests. Priority, GitHub defaults, and workflow triggers remain independent operational metadata.
|
||||
|
||||
Label migrations preserve meaning before removing aliases: add the canonical replacement, verify the labelable, then remove the obsolete assignment. A label is deleted only after no pull request or Issue still uses it, and unrelated labels are never replaced as a set.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Unprefixed labels.** Plain names reduce visual noise, but they do not identify whether a label classifies intent, domain, source, priority, or automation. Retaining both plain and namespaced synonyms also makes queries and policy enforcement ambiguous.
|
||||
|
||||
**One undifferentiated label set.** A label's presence would not prove that both intent and semantic scope were considered.
|
||||
|
||||
**A fixed area allowlist in repository policy.** Durable repository domains evolve. The `area/*` namespace remains mechanically recognizable while live descriptions carry the extensible inventory.
|
||||
|
||||
**Package- or path-derived areas.** Areas describe semantic impact across package boundaries, while changed paths include incidental tests, documentation, and support files.
|
||||
|
||||
**Separate labels for every delivery shell or media lifecycle.** Browser and Electron delivery share one graphical domain, and artifact, attachment, and multimodal delivery currently share one review/query domain. A split belongs in a later taxonomy change only when it restores useful independent classification.
|
||||
|
||||
**Broad implementation labels in place of semantic domains.** A concrete capability is not merely its tool, interface, filesystem, or process implementation. Generic implementation areas apply only when their own contracts change.
|
||||
|
||||
**Kinds on Issues.** Native Issue Type already owns that classification; duplicating it as a label creates drift.
|
||||
|
||||
**Exactly one area per pull request.** Coherent changes can materially affect several independent contracts, and dropping secondary areas hides affected scope.
|
||||
|
||||
## Consequences
|
||||
|
||||
Reviewers and automation can query intent, semantic scope, provenance, priority, and operational triggers independently. Maintainers must read the change and the live label descriptions instead of inferring classification from title prefixes or paths. The live catalog, this rationale, and policy enforcement must move together when a kind or a non-obvious area boundary changes, and taxonomy migrations carry an explicit historical backfill and verification cost.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Agent Note: 统一 GitHub 标签分类体系
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-08-unified-github-label-taxonomy.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度，或同时保留同义的无前缀标签与带命名空间的标签，都会使查询含义模糊；封闭的领域清单则会迫使新领域归入不准确的类别。
|
||||
|
||||
Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
|
||||
|
||||
## 决策
|
||||
|
||||
每项开放或已合并的 PR 都带有恰好一个规范的 `kind/*` 标签，以及至少一个表示实质受影响领域的 `area/*` 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
|
||||
|
||||
### 变更类型
|
||||
|
||||
类型集合封闭且互斥：
|
||||
|
||||
| 变更类型 | 含义 |
|
||||
|---|---|
|
||||
| `kind/feature` | 新增行为或有意改变行为。 |
|
||||
| `kind/bug-fix` | 修正错误行为。 |
|
||||
| `kind/doc` | 以文档变更为主导意图。 |
|
||||
| `kind/testing` | 在不改变产品行为的前提下修改测试或测试基础设施。 |
|
||||
| `kind/cleanup` | 在保持行为不变的前提下，维护或简化实现或仓库流程。 |
|
||||
| `kind/dependency` | 在没有其他主导意图时更新依赖。 |
|
||||
|
||||
类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
|
||||
|
||||
仓库政策会拒绝不支持的 `kind/*` 值，并将统一过程中移除的所有别名列为保留名称：`kind/bug`、`kind/documentation`、`feature`、`bug-fix`、`doc`、`cleanup`、`testing`、`dependencies`、`ci`、`cli`、`llm` 和 `web-search`。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
|
||||
|
||||
### 领域
|
||||
|
||||
领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 `area/*` 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
|
||||
|
||||
- `area/web` 覆盖浏览器与 Electron 图形界面，`area/vscode` 覆盖编辑器扩展，`area/api` 覆盖跨界面协议与各语言 SDK。
|
||||
- `area/planning` 覆盖目标、计划、待办和调度，`area/workflow` 则覆盖可执行工作流与后台任务运行时。
|
||||
- `area/artifact` 有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。
|
||||
- `area/tools` 适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。
|
||||
- `area/hooks` 表示 Claude Code 与 Codex 桥接，`area/infra` 覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，`area/windows` 覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
|
||||
|
||||
领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 `area/<lowercase-kebab-case>` 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
|
||||
|
||||
### Issue 与迁移
|
||||
|
||||
Issue 使用原生 Issue Type，而不是 `kind/*`；其 `area/*` 标签仍然可选。`source/*` 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
|
||||
|
||||
迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**无前缀标签。** 无前缀名称可以减少视觉噪声，但无法表明标签分类的是意图、领域、来源、优先级还是自动化用途。同时保留无前缀和带命名空间的同义标签，也会使查询和政策执行含义模糊。
|
||||
|
||||
**不区分维度的单一标签集合。** 某个标签存在，并不能证明意图和语义范围都经过了考虑。
|
||||
|
||||
**仓库政策中的固定领域允许清单。** 持久的仓库领域会演进。`area/*` 命名空间仍可机械识别，而现行说明承载可扩展清单。
|
||||
|
||||
**按包或路径派生的领域。** 领域描述跨越包边界的语义影响，而变更路径会包含偶然涉及的测试、文档和支持文件。
|
||||
|
||||
**为每种交付载体或媒体生命周期单设标签。** 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
|
||||
|
||||
**用宽泛的实现标签取代语义领域。** 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
|
||||
|
||||
**在 Issue 上使用类型标签。** 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
|
||||
|
||||
**每个 PR 恰好一个领域。** 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
|
||||
|
||||
## 后果
|
||||
|
||||
评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。
|
||||
@@ -13,7 +13,7 @@ updates:
|
||||
cooldown:
|
||||
default-days: 30
|
||||
labels:
|
||||
- "cleanup"
|
||||
- "kind/dependency"
|
||||
- "area/infra"
|
||||
|
||||
- package-ecosystem: "uv"
|
||||
@@ -25,7 +25,7 @@ updates:
|
||||
cooldown:
|
||||
default-days: 30
|
||||
labels:
|
||||
- "cleanup"
|
||||
- "kind/dependency"
|
||||
- "area/infra"
|
||||
|
||||
- package-ecosystem: "github-actions"
|
||||
@@ -37,5 +37,5 @@ updates:
|
||||
cooldown:
|
||||
default-days: 30
|
||||
labels:
|
||||
- "cleanup"
|
||||
- "kind/dependency"
|
||||
- "area/infra"
|
||||
@@ -12,6 +12,29 @@ const AUDIT_MARKER = '<!-- dsh-issue-policy -->'
|
||||
const OWNER_LINE = /^Owner: @([A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?)$/
|
||||
const TYPES = new Set(['Idea', 'Feature', 'Bug', 'Research', 'Task'])
|
||||
const PRIORITIES = ['p0', 'p1', 'p2', 'p3']
|
||||
const PR_KINDS = new Set([
|
||||
'kind/feature',
|
||||
'kind/bug-fix',
|
||||
'kind/doc',
|
||||
'kind/testing',
|
||||
'kind/cleanup',
|
||||
'kind/dependency',
|
||||
])
|
||||
// Aliases removed by the unified taxonomy migration remain reserved so they cannot be recreated.
|
||||
const LEGACY_LABELS = new Set([
|
||||
'kind/bug',
|
||||
'kind/documentation',
|
||||
'feature',
|
||||
'bug-fix',
|
||||
'doc',
|
||||
'cleanup',
|
||||
'testing',
|
||||
'dependencies',
|
||||
'ci',
|
||||
'cli',
|
||||
'llm',
|
||||
'web-search',
|
||||
])
|
||||
const TERMINAL_STATUSES = new Set(['Done', 'No action'])
|
||||
const ACTIVE_STATUS_ORDER = config.statuses.filter((status) => !TERMINAL_STATUSES.has(status))
|
||||
|
||||
@@ -224,8 +247,14 @@ export function retainIssueReferences(references, issues) {
|
||||
export function validateIssue(issue) {
|
||||
const errors = validateBody(issue)
|
||||
const status = issue.status
|
||||
const invalidLabels = issue.labels.filter(
|
||||
(label) => label.startsWith('kind/') || LEGACY_LABELS.has(label),
|
||||
)
|
||||
|
||||
if (!/\p{Script=Han}/u.test(issue.title)) errors.push('Issue 标题必须包含中文')
|
||||
if (invalidLabels.length > 0) {
|
||||
errors.push(`Issue 不得使用 PR kind 或旧版标签：${invalidLabels.join(', ')}`)
|
||||
}
|
||||
if (
|
||||
/^\s*(?:\[(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^\]]+)[^\]]*\]|(?:Idea|Feature|Bug|Research|Task|P[0-3]|Inbox|Backlog|Ready|In progress|In review|Done|No action|Owner|area\/[^:： ]+)\s*[:：-])/iu.test(
|
||||
issue.title,
|
||||
@@ -261,12 +290,24 @@ export function validateIssue(issue) {
|
||||
export function validatePullRequest(input) {
|
||||
if (!requiresPullRequestPolicy(input)) return []
|
||||
const errors = []
|
||||
const kinds = input.labels.filter((label) => label.startsWith('kind/'))
|
||||
const kinds = input.labels.filter((label) => PR_KINDS.has(label))
|
||||
const unknownKinds = input.labels.filter(
|
||||
(label) => label.startsWith('kind/') && !PR_KINDS.has(label) && !LEGACY_LABELS.has(label),
|
||||
)
|
||||
const legacyLabels = input.labels.filter((label) => LEGACY_LABELS.has(label))
|
||||
const sourceLabels = input.labels.filter((label) => label.startsWith('source/'))
|
||||
const priorities = input.labels.filter((label) => PRIORITIES.includes(label))
|
||||
const areas = input.labels.filter((label) => label.startsWith('area/'))
|
||||
|
||||
if (input.references.all.length === 0) errors.push('PR 正文必须引用至少一个同仓库 Issue')
|
||||
if (kinds.length !== 1) errors.push(`PR 必须恰好有一个 kind/*，当前为 ${kinds.length}`)
|
||||
if (kinds.length !== 1) {
|
||||
errors.push(`PR 必须恰好有一个允许的 kind/*，当前为 ${kinds.length}`)
|
||||
}
|
||||
if (unknownKinds.length > 0) {
|
||||
errors.push(`PR 含不支持的 kind/*：${unknownKinds.join(', ')}`)
|
||||
}
|
||||
if (legacyLabels.length > 0) errors.push(`PR 含旧版标签：${legacyLabels.join(', ')}`)
|
||||
if (sourceLabels.length > 0) errors.push(`source/* 仅用于 Issue：${sourceLabels.join(', ')}`)
|
||||
if (priorities.length > 1) errors.push(`PR 最多有一个 p0–p3，当前为 ${priorities.length}`)
|
||||
if (areas.length === 0) errors.push('PR 必须至少有一个 area/*')
|
||||
for (const number of input.references.all) {
|
||||
|
||||
@@ -27,6 +27,41 @@ const legalIssue = {
|
||||
stateReason: null,
|
||||
}
|
||||
|
||||
const canonicalKinds = [
|
||||
'kind/feature',
|
||||
'kind/bug-fix',
|
||||
'kind/doc',
|
||||
'kind/testing',
|
||||
'kind/cleanup',
|
||||
'kind/dependency',
|
||||
]
|
||||
|
||||
// Keep an independent oracle rather than importing the implementation's reserved set.
|
||||
const legacyLabels = [
|
||||
'kind/bug',
|
||||
'kind/documentation',
|
||||
'feature',
|
||||
'bug-fix',
|
||||
'doc',
|
||||
'cleanup',
|
||||
'testing',
|
||||
'dependencies',
|
||||
'ci',
|
||||
'cli',
|
||||
'llm',
|
||||
'web-search',
|
||||
]
|
||||
|
||||
const reviewedPull = (labels) => ({
|
||||
isDraft: false,
|
||||
authorType: 'User',
|
||||
reviewRequestCount: 1,
|
||||
reviewCount: 0,
|
||||
labels,
|
||||
references: { all: [2], resolving: [], related: [2] },
|
||||
issues: new Map([[2, { priority: null }]]),
|
||||
})
|
||||
|
||||
test('counts only text outside details', () => {
|
||||
assert.deepEqual(countVisibleUnits('支持 GitHub Project。<details>隐藏文字</details>'), {
|
||||
units: 4,
|
||||
@@ -92,6 +127,22 @@ test('rejects metadata prefixes in an Issue title', () => {
|
||||
assert.ok(errors.includes('Issue 标题不得带 Type、Priority、Status、area 或 Owner 前缀'))
|
||||
})
|
||||
|
||||
test('reserves PR kind and legacy labels for pull requests', () => {
|
||||
for (const label of [
|
||||
...canonicalKinds,
|
||||
'kind/experimental',
|
||||
...legacyLabels,
|
||||
]) {
|
||||
assert.ok(
|
||||
validateIssue({ ...legalIssue, labels: [label] }).some((error) =>
|
||||
error.startsWith('Issue 不得使用 PR kind 或旧版标签：'),
|
||||
),
|
||||
label,
|
||||
)
|
||||
}
|
||||
assert.deepEqual(validateIssue({ ...legalIssue, labels: ['area/web', 'source/member'] }), [])
|
||||
})
|
||||
|
||||
test('keeps terminal Status aligned with the native close reason', () => {
|
||||
assert.deepEqual(
|
||||
validateIssue({ ...legalIssue, status: 'Done', state: 'closed', stateReason: 'completed' }),
|
||||
@@ -260,22 +311,39 @@ test('requires repository PR labels in the enforcement scope', () => {
|
||||
references: { all: [2], resolving: [], related: [2] },
|
||||
issues: new Map([[2, { priority: null }]]),
|
||||
})
|
||||
assert.ok(errors.includes('PR 必须恰好有一个 kind/*，当前为 0'))
|
||||
assert.ok(errors.includes('PR 必须恰好有一个允许的 kind/*，当前为 0'))
|
||||
assert.ok(errors.includes('PR 必须至少有一个 area/*'))
|
||||
})
|
||||
|
||||
test('accepts repository-extensible kind labels', () => {
|
||||
assert.deepEqual(
|
||||
validatePullRequest({
|
||||
isDraft: false,
|
||||
authorType: 'User',
|
||||
reviewRequestCount: 1,
|
||||
reviewCount: 0,
|
||||
labels: ['kind/dependency', 'area/infra'],
|
||||
references: { all: [2], resolving: [], related: [2] },
|
||||
issues: new Map([[2, { priority: null }]]),
|
||||
}),
|
||||
[],
|
||||
test('accepts exactly the canonical kinds with extensible areas', () => {
|
||||
for (const kind of canonicalKinds) {
|
||||
assert.deepEqual(validatePullRequest(reviewedPull([kind, 'area/future-domain'])), [], kind)
|
||||
}
|
||||
})
|
||||
|
||||
test('rejects multiple, unknown, legacy, and Issue-source PR labels', () => {
|
||||
assert.ok(
|
||||
validatePullRequest(
|
||||
reviewedPull(['kind/feature', 'kind/doc', 'area/web']),
|
||||
).includes('PR 必须恰好有一个允许的 kind/*，当前为 2'),
|
||||
)
|
||||
assert.ok(
|
||||
validatePullRequest(reviewedPull(['kind/experimental', 'area/web'])).includes(
|
||||
'PR 含不支持的 kind/*：kind/experimental',
|
||||
),
|
||||
)
|
||||
for (const label of legacyLabels) {
|
||||
assert.ok(
|
||||
validatePullRequest(reviewedPull(['kind/feature', 'area/web', label])).some((error) =>
|
||||
error.startsWith('PR 含旧版标签：'),
|
||||
),
|
||||
label,
|
||||
)
|
||||
}
|
||||
assert.ok(
|
||||
validatePullRequest(
|
||||
reviewedPull(['kind/feature', 'area/web', 'source/internal-pr']),
|
||||
).includes('source/* 仅用于 Issue：source/internal-pr'),
|
||||
)
|
||||
})
|
||||
|
||||
|
||||
@@ -119,7 +119,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
|
||||
- **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)).
|
||||
- **Plan unit, e2e, and snapshot coverage** for new seams, lifecycle shapes, and transcript surfaces; missing snapshot-harness support is part of the implementation, not deferred follow-up.
|
||||
- **Choose PR history deliberately.** Split independent changes; fix the introducing PR before propagation. Standalone PRs and official stacks may merge-forward or rebase after review. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; an in-progress merge-forward preserves its checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)).
|
||||
- **Label PRs:** one kind (`feature`/`bug-fix`/`doc`/`testing`/`cleanup`), each matching area; the [taxonomy](.agents/notes/implemented/process/2026-07-25-semantic-pr-label-taxonomy.md) is extensible.
|
||||
- **Labels:** one PR `kind/*`, all material `area/*`, and native Issue Type ([taxonomy](.agents/notes/implemented/process/2026-08-08-unified-github-label-taxonomy.md)).
|
||||
- TODO markers: `FIXME`/`TODO`/`XXX` by urgency ([semantics](docs/development.md)).
|
||||
- Files end with exactly one trailing newline; `git diff --cached --check` (pre-commit) gates it.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user