Unified GitHub label taxonomy
统一 GitHub 标签分类体系
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 o
English
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 these classification rules 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 product or engineering subjects rather than temporary initiatives, ownership, or every path touched incidentally. A pull request carries multiple areas when it changes distinct behavior or APIs, but it does not combine an umbrella and a narrower label for the same change. GitHub's live area/* names and descriptions own the current inventory; this record defines selection cases that cannot fit reliably in short label descriptions.
area/webcovers browser and Electron graphical interfaces,area/vscodecovers the editor extension, andarea/apicovers cross-interface protocols and language SDKs.area/planningcovers goals, plans, todos, and scheduling, whilearea/workflowcovers executable workflows and background job runtimes.area/artifactdeliberately combines artifacts, attachments, and multimodal delivery. Split labels become justified only when those concerns again need independent review or queries.area/toolsapplies to generic registry, schema, and execution contracts. A concrete capability uses its own area unless it also changes one of those contracts.area/hooksmeans the Claude Code and Codex bridges,area/infracovers build, release, CI, repository gates, generators, dependencies, and developer tooling, andarea/windowscovers 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 how an Issue was created 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 product or engineering subjects. A concrete capability is not merely its tool, interface, filesystem, or process implementation. Generic implementation areas apply only when their own behavior or API changes.
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 APIs or behaviors, and dropping secondary areas hides affected scope.
Consequences
Reviewers and automation can query intent, semantic scope, how an Issue was created, 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.
中文
问题
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 修改不同的行为或 API 时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项变更。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 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
用宽泛的实现标签取代产品或工程主题。 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身行为或 API 变化时适用。
在 Issue 上使用类型标签。 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
每个 PR 恰好一个领域。 内聚的变更可能对多个独立 API 或行为产生实质影响，丢弃次要领域会隐藏受影响范围。
后果
评审人和自动化流程可以分别查询意图、语义范围、Issue 的创建方式、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。