etcd 项目 Issue 分类分诊指南：标签体系、优先级评定与社区协作流程

导读

本文基于 Documentation/contributor-guide/triage_issues.md，系统讲解 etcd 开源项目如何对 GitHub Issue 进行"分类分诊（triage）"。无论你是有权限直接给 Issue 打标签的 Reviewer / Member，还是想通过提 Issue、认领 Issue 参与贡献的普通开发者，读完本文都能掌握 etcd 的 type、area、priority 标签体系、七步分诊流程，以及"help wanted / good first issue"等面向新贡献者的协作约定。文章同时结合仓库中的 OWNERS、community-membership.md、CONTRIBUTING.md 等源码与社区文档，帮助读者把分诊规则映射到仓库的实际结构与角色权限上。

为什么 etcd 需要一套 Issue 分诊指南

etcd 是一个被广泛用于分布式系统关键数据的可靠键值存储仓库。随着项目规模增长，每天的 Issue 数量、质量参差不齐：有的是真 Bug，有的是使用求助，有的是重复报告，有的则属于 grpc、golang 等上游项目的问题。若不对它们及时分类、打标、定优先级，维护者将疲于应付海量通知，真实 Bug 与测试不稳定（flake）问题反而会被淹没。

因此分诊文档开宗明义地给出了目标（Purpose）：加速 Issue 管理（Speed up issue management）。etcd 通过 标签（labels） 来标识 Issue 的公共属性，例如 area（影响模块）、type（类型）与 priority（优先级）。新提交的 Issue 通常没有任何标签，而 etcd 的 maintainer、reviewer 与 member 需要按本文档的约定补齐这些标签，从而：

• 让项目健康度（bug、flake 的数量与趋势）可被看见；
• 帮助贡献者按自己的技能领域快速找到可认领的工作（例如先修 Bug 与测试 flake，再实现新功能）；
• 为 backlog 管理提供排序依据。

分诊的适用范围与权限边界

文档的 Scope 一节明确了两点：

1. 本文档是 etcd 新增 Issue 分诊的主要指南；
2. 所有贡献者都被鼓励参与 Issue 管理，以减轻维护者负担，但只有具备 triage 权限的人才能执行打标签、关闭 Issue 等写操作——例如文档中多次出现"如果你有 triage 权限请关闭它，否则 @etcd-io/members 提请在社区中拥有 triage 权限的成员来处理"。

在仓库的社区成员文档 community-membership.md 中可以看到这种权限对应的角色阶梯：

角色	主要职责	在仓库中的定义
Member	社区活跃贡献者，可被指派 Issue/PR	etcd GitHub 组织成员，被授予 triage access
Reviewer	评审其他成员的贡献，LGTM 计入合并条件	OWNERS 文件中的 reviewer 条目
Maintainer	设定项目方向与优先级	OWNERS 文件中的 approver 条目

其中，Member 的权限清单明确包含"Granted triage access to etcd project"，Reviewer 同样被授予 triage access。仓库根目录的 OWNERS 展示了 approver 与 emeritus_approver（退休维护者）的组织结构，而 OWNERS_ALIASES 定义了 sig-etcd-chairs 与 sig-etcd-tech-leads 两个别名组。想晋升为 member 或 reviewer 的贡献者，应参阅社区成员资格文档中关于"由两位来自不同公司的活跃 maintainer/reviewer 赞助"等要求。

Step 1：找到需要分诊的 Issue

仓库的 CONTRIBUTING.md 指出，etcd 的所有工作都记录在 GitHub Issue 跟踪器中，因此"被正确打标签的 Issue"是新手找活儿的第一入口。分诊文档推荐用 GitHub Issue 搜索界面组合过滤器定位待分诊项，以下四类检索思路值得原文保留（均可通过 GitHub 的 Issue 搜索语法实现）：

• 无任何标签的 Issue：is:issue is:open sort:updated no:label——这是分诊的首选目标池；
• 近期新建的 Issue：is:issue is:open；
• 未指派但已关联 PR 的 Issue：is:open is:issue no:assignee linked:pr——通常意味着有人在推进但归属不清；
• 零评论的 Issue：is:open is:issue comments:0——等待首次响应；
• 带 help wanted 的 Issue：is:open is:issue label:"help wanted"——适合寻找可认领工作。

上述过滤器配合排序条件（如 sort:updated）即可持续产出待分诊队列。普通贡献者若发现 good first issue、help wanted 或 priority/important 相关标签下已无空闲 Issue，可以像 CONTRIBUTING.md 建议的那样联系维护者请求多分诊一些 Issue。

Step 2：先验证 Issue 是否属于 etcd 且不重复

分诊的第一步不是急着打标签、定优先级，而是判断 Issue 是否真的属于 etcd 项目、是否与已有报告重复。这一判断直接决定 Issue 的去留。

不属于 etcd 的 Issue

etcd 重度依赖 gRPC、Go 等生态，因此偶尔会出现本应提交给 grpc 或 golang 上游项目的 Issue。这类 Issue 的处理方式：

• 回复报告者，请其到对应上游项目提交；
• 一般可以直接关闭，除非维护者与报告者认为有必要保留用于跟踪；
• 关闭前同样遵循权限规则：有 triage 权限直接关闭，否则 @etcd-io/members 求助。

重复的 Issue

如果确认是重复报告，处理方式类似：在评论中说明"这是重复 Issue"并附上原始 Issue 的引用，然后由具备权限者关闭（或 @etcd-io/members 协助）。仓库的 Bug 报告指南 reporting_bugs.md 在面向报告者的要求中同样强调 "Unique. Do not duplicate existing bug reports"，并说明重复的 Bug 报告会被关闭——分诊规则与报告规范在这里形成闭环。

Step 3：为 Issue 应用正确的 type 标签

type 标签揭示 Issue 的本质，帮助团队看清项目健康度——是既有 Bug、测试不稳定问题，还是新功能请求。文档建议优先区分以下四类。

支持请求（Support requests）与 question 类 Issue

原则：etcd 的支持策略是"广撒网"——通过已知问题清单、FAQ、高质量文档来覆盖共性需求，避免在可行时提供一对一的 1:1 支持。因此，误用 Bug/Feature 模板提交的支持类请求会被引导到 discussions 渠道。文档归纳了四类常见"伪 Issue"：

1. 关于已充分文档化的既有特性的配置/运维问题（文档原文给出了 Issue #15945 为例）。处理要点：若该特性其实文档不佳，则应打上 area/documentation 标签并提出文档改进，防止后来者再次踩坑；
2. 针对不受支持 etcd 版本的 Bug 报告或提问（原文示例 Issue #15796）。处理要点：援引受支持版本说明文档，尽快建议对方升级到受支持版本的最新 patch 版本；项目会限制为不运行受支持版本/不打补丁版本的用户投入过多精力；
3. 未提供完整可复现步骤、或贡献者无法复现的 Bug 报告（原文示例 Issue #15740）。处理要点：限制团队自行复现的投入，敦促用户补齐验收 Bug 所必需的信息；
4. 用 Feature/Bug 模板提交的泛化提问（原文示例 Issue #15914）。此类提问可能沉淀出有价值的 FAQ 条目。

一旦判定为支持请求，分诊者需要三步处理：

1. 添加 type/support 或 type/question 标签；

2. 在 Issue 下粘贴一段标准说明评论，告知提交者该支持 Issue 会被转移到 Discussion 论坛，并引导其先检索已有讨论、阅读用户文档与 FAQ。文档原文给出了完整模板（节选其要点，可直接复用）：

   Thank you for your question, this support issue will be moved to our Discussion Forums.

   We are trying to consolidate the channels to which questions for help/support are posted so that we can improve our efficiency in responding to your requests, and make it easier for you to find answers to frequently asked questions and how to address common use cases.

   We regularly see messages posted in multiple forums, with the full response thread only in one place or, worse, spread across multiple forums. Also, the large volume of support issues on GitHub is making it difficult for us to use issues to identify real bugs.

   Members of the etcd community use Discussion Forums to field support requests. Before posting a new question, please search these for answers to similar questions, and also familiarize yourself with: 1. user documentation 2. frequently asked questions.

   Again, thanks for using etcd and raising this question.

   The etcd team

3. 点击 Issue 面板右侧的 Convert to discussion，选择恰当的讨论分类完成转换。

这段处理流程与仓库 reporting_bugs.md 中"请先提供具体版本/环境/配置、附上 etcd 启动日志、最小化复现、保持唯一与单主题"等要求互为呼应：分诊者在判断"是否为合格 Bug"时，实际上是在用这份报告规范做验收。

Bug 报告（Bug reports）

• 通过 Bug 模板提交的 Issue 理论上已带 type/bug；若缺失则手动补上。
• 下一步是验证它是否真的是 Bug：
  • 若不是，在评论中写明结论并关闭琐碎 Issue；
  • 对非琐碎但有疑问的，等待报告者回应、确认其是否有异议；报告者 30 天内不回复则关闭；
  • 若问题无法复现或缺少信息，应在 Issue 尚"新鲜"时尽快留言索取信息。

功能请求（Feature requests）

新功能应通过 etcd 的 feature request 模板提交，理论上已带 type/feature；若缺失则手动补上。

测试不稳定（Test flakes）

测试 flake 是一种被 etcd 单独跟踪的特殊 Bug，因为它属于高优先级治理对象。应通过 test flake 模板创建，理论上自带 type/flake；若缺失则手动补上。仓库侧有大量佐证：

• CONTRIBUTING.md 专门给出"Check for flaky tests"小节，说明如何用 stress 工具复现 flaky test，并要求"若找到 flaky 测试请先检查是否已有 type/flake 的 Issue，没有则新开一个"；
• 仓库内还维护了专门的健壮性测试框架 tests/robustness/README.md，其 "Robustness track record" 表格记录了历年发现的一致性/正确性问题，并对应给出 make test-robustness-issueNNNNN 形式的复现脚本——这正是"type/flake、area/robustness-testing 问题被优先治理"在代码库中的落地体现。

Step 4：界定受影响的领域（area）

area 标签标注 Issue 波及的代码/项目领域，帮助贡献者按技能认领工作；如果 Issue 跨越多个领域，应添加多个 area 标签。文档原表给出当前活跃使用的 area 标签及其使用说明，完整继承如下：

Label	Notes（使用说明）
area/external	跟踪标签，用于标记源自 etcd 外部的 Issue
area/community	（社区相关）
area/raft	Raft 共识模块相关
area/clientv3	clientv3 客户端库相关
area/performance	性能相关
area/security	安全相关
area/tls	TLS 相关
area/auth	认证鉴权相关
area/etcdctl	etcdctl 命令行工具相关
area/etcdutl	etcdutl 工具相关
area/contrib	注意区别于 area/community；专指 contrib/ 目录下由社区维护、不属于 etcd 核心项目的脚本或文件（例如 contrib/mixin、contrib/systemd 等）相关 Issue
area/documentation	文档相关
area/tooling	通常指构建、测试、发布流程中使用的第三方/外部工具或程序，例如生成 SBOM 的工具
area/testing	测试相关
area/robustness-testing	健壮性测试相关（对应 tests/robustness 框架）

可以看到，这些标签几乎与仓库顶层目录一一对应：raft 实现在 server/etcdserver（含 Raft 协议相关代码），客户端库在 client/v3，命令行工具在 etcdctl 与 etcdutl，社区维护脚本在 contrib。这解释了为什么 area 标签能帮助贡献者"按自己的技能或对代码库的熟悉程度"快速找到契合的 Issue。

Step 5：评定优先级（priority）

如果 Issue 没有优先级标签，说明它尚未被正式排期。priority 标签让项目清楚"现在该做什么、什么处于 backlog"。文档原表的五个优先级级别完整继承如下：

Priority label	含义	示例
priority/critical-urgent	维护者必须确保（各自领域的）这些 Issue 被积极处理——放下手头工作，马上处理。这类问题应在下一个 release 前修复	核心特性中用户可见的严重 Bug；tier1 支持平台上的构建失败；测试与关键安全问题
priority/important-soon	必须排定人力并在当前或近期着手，理想情况下赶上下一版本
priority/important-longterm	长期重要，但当前可能没有排定人力，或需要跨多个版本完成
priority/backlog	一致认为属于"锦上添花"，但短期内无人手可做。在此期间社区贡献非常受欢迎；不过若评审者忙于更高优先级 Issue（例如临近发版），评审可能会慢
priority/awaiting-more-evidence	可能有用，但证据尚不足以推动落地	多为"潜在好点子"的占位，以免被彻底遗忘；每当相关话题再次出现时可引用或去重

与 area 相似，priority 标签也需要与 CONTRIBUTING.md 中给贡献者指路的原则协同：新手看 good first issue，进阶者看 help wanted，高级贡献者可以处理带 priority/important 的、代表当下最相关工作量的 Issue。

Step 6：支持新贡献者（help wanted 与 good first issue）

一旦 type 与 area 已确定，分诊者还应评估该 Issue 是否适合经验较浅的贡献者。标签体系的关键约束是：good first issue 是 help wanted 的子集——所有 good first issue 同时带有 help wanted。

help wanted 的三条准入标准

被标记为 help wanted 的 Issue 必须同时满足：

• Low Barrier to Entry（低门槛）：对新手友好、容易上手；
• Clear（清晰）：任务已达成社区共识，无需再在社区反复讨论；
• Goldilocks priority（恰到好处的优先级）：不能高到必须由核心贡献者亲自做，也不能低到核心贡献者不值得花时间评审、答疑、帮助其进入某个 release。

good first issue 的五条准入标准

标记为 good first issue 意味着面向首次贡献者，并承诺成员会特别关照其 PR、一路护送走完流程。新贡献者不应被迫自己找 approver、催评审、猜测试命令，或独自判断"构建失败是否因为 flake"——要让他们感到被欢迎和重视，并承诺首次贡献会获得额外帮助。在完成一两个 good first issue 后，贡献者就可以进阶到 help wanted 了。其准入门槛更高：

• No Barrier to Entry：无需高级环境搭建或领域知识即可着手；
• Solution Explained：Issue 中清晰描述了推荐解法；
• Gives Examples：给出类似实现的链接，作为新人的参照范本；
• Identifies Relevant Code：在 Issue 中链接需要修改的相关代码与测试；
• Ready to Test：应当存在可修改的既有测试，或有可直接套用的既有测试用例；如果该代码领域还没有测试，打标签前应先补上测试 fixture——这类准备工作本身往往就是很好的 help wanted 任务。

该环节与仓库 CONTRIBUTING.md 的建议（新手先找 good first issue、更熟练后再看 help wanted）完全一致，也与社区成员资格文档 community-membership.md 中 "New contributors should be welcomed" 的约定相衔接。

Step 7：后续跟进（Follow up）

初次分诊完成后，Issue 还需随时间推移被反复评估，以免被错误地变陈旧（stale）。文档给出三类跟进动作：

跟踪重要 Issue

如果某 Issue 未来可能被 stale bot 自动关闭，但它对 etcd 确实重要，则：

• 打上 stage/tracked 标签；
• 移除已有的 stale 标签。

从而确保项目不会"丢失视线"。

关闭不完整 Issue

报告者 30 天未补充足够信息的 Issue 应被关闭；之后若有人提供新信息，Issue 随时可以重新打开。

检查未完成的工作

如果某个由开发者认领的 Issue 在 30 天内没有产生任何 PR，应联系认领者友好询问工作进展，或请其在必要时释放对该 Issue 的所有权。

值得注意的是，仓库配套的 PR 分诊文档 triage_prs.md 给出了对应的时间轴：评审意见 15 天未处理则提醒 PR 作者、90 天未回复则尽量以新提交更新 PR、180 天未处理则关闭非活跃 PR。Issue 侧的 30 天规则与 PR 侧的时间轴共同构成 etcd 处理"工作流停滞"的完整策略。

结语：分诊规则在仓库中的落地全貌

把这份分诊指南放回仓库看，它不是孤立的文档，而是与整个贡献流程咬合在一起：

• 谁能分诊：由 community-membership.md 定义的 Member/Reviewer/Maintainer 角色决定，角色本身沉淀在 OWNERS 与 OWNERS_ALIASES 中；
• Issue 从哪来：报告者遵循 reporting_bugs.md 的规范提交（具体、可复现、隔离、唯一、单主题）；
• 分诊产出什么：一套覆盖 type（bug/flake/feature/question）、area（raft/clientv3/etcdctl……）、priority（critical-urgent → awaiting-more-evidence）、stage/tracked 以及 help wanted / good first issue 的标签组合；
• 分诊后流向哪里：被确认的 bug/flake 进入修复队列并接受 tests/robustness 等框架的回归验证，新贡献者顺着标签找到可认领任务并逐步晋升。

对希望参与 etcd 的开发者而言，本文介绍的分诊流程既是一份"贡献者工作手册"，也是一份"晋升路径说明书"：从看懂标签、补充标签、帮助验证 Issue，到以 Reviewer 身份参与分诊与评审，每一步都有明确的标准与配套文档可循。