Kubernetes issue triage

一、为什么我们需要Issue triage

 

Issue triage 是交由 SIG 接收和审查新的 GitHub issues 和 requests 的过程，并组织 SIG 内的成员或其他SIG 的成员采取相应活动。Traiging 是根据 优先级/紧急度、问题的SIG所有权以及问题的类型（错误、功能等）对问题进行分类并提出请求。一个或多个SIG有责任去处理这些 issues 和 requests。

 

Triage 的产生可以是异步且持续的。一些 Kubernetes SIGs 和 项目已经采用了自己的分类方式。

 

 

二、Triage 有什么优势

 

• 快速的对 issue 进行管理

• 通过缩短响应时间来保持 contributors 的参与度

• 防止无休止的进行重复性工作

• 以中立的流程去替换 “特殊的请求” 和 一次性请求

• 使得拥有更大的透明度，增加协作并参与有趣的讨论，产生更明智的决策

• 它有助于建立优先级、协商和决策技巧，这对于大多数技术人员而言至关重要

• 它增强了SIG社区运营和文化

 

 

三、如何分类：分步流程

 

Triage 相关工具

旨在引导你完成标准的分类程序，首先介绍工具和技巧

 

• 机器人

所有的贡献者都可以打开新的issue并发表有关于他人问题的评论。但是，分配特定标签（例如：traige）、更改里程碑或者关闭其他贡献者问题的权限仅授予问题的作者、assigness 和 组织成员。因此，我们使用机器人来管理标签和分类。有关命令和权限的完整列表，请参见Prow命令参考页。

 

• Gubernetor

Gubernetor 提供了一个仪表板，可以告诉你哪些pull request 正在等待你的反馈，哪些 pull request 正在等待贡献者进行响应。请注意，Gubernetor仅显示 Pull request 。你将看不到分配给你的问题。

 

• Triage Party

Triage Party 是通过 GitHub API 构建的大型项目GitHub issue分类工具。它于 2020年4月公开，促进了 “大规模多用户GitHub分类” 并减少了贡献者响应延迟。

 

它的一些功能：

• 跨多个存储库的查询

• GitHub上不可能的查询：

• • 对话方向（tag: recv，tag: send）

  • 持续时间（updated: +30d）

  • 正则表达式（label: priority/.*）

  • 反应（reactions: >=5）

  • 评论人气（comments-per-month: >0.9）

• 多人游戏模式：用于一组问题的同时组分类

• 用于将问题组打开为浏览器选项卡的按钮（必须禁用弹出窗口）

• “ Shift-Reload”用于实时数据提取

 

• GitHub Project Boards

GitHub 提供了类似于 kanban boards 的 Project Boards，去帮助团队组织和跟踪其工作流程以完成工作。Release 团队依赖这个Project board来计划发布新的Kubernetes releases。他们还将其用作与归档，以显示过去针对于发行版本所做的相关工作。

 

• 开发统计

CNCF创建了一套基于Grafana的仪表板和图表，用于收集与CNCF项目相关的指标。该 Kubernetes 仪表板 可用于帮助 SIGs 查看他们的工作流程，其中包括许多的实时指标：

• 问题速度：解决问题的速度

• PR速度：包括每个SIG的PR工作量，批准和合并的PR时间以及其他数据

 

 

来自 SIGs 的关键点和建议

 

SIGs 每周或每月都会召开会议，对问题进行分流。以下是关于它们的程序的一些细节：

 

运行 Triage 会议：来自 api-machinery 的 Tips

 

api-machinery SIG 发现，Triage 会议为新人提供了宝贵的聆听、学习和开始贡献的机会。api-machinery 每周二和周四都会举行 Triage 会议，并通过他们的 Youtube 播放列表对会议记录进行存档；这里有一个例子。

 

在典型的分流会议中，api-machinery 成员会对上一次会议后没有 Triage 的问题进行分类，使用一个简单的查询和问题编号来跟踪打开状态的 PR和问题。他们通常会：

 

• 简单阅读注释和代码，了解问题的内容。

• 通过共识确定它是否属于 api-machinery SIG。

• 如果不属于该 SIG，请删除 sig/api-machinery 标签。

• 如果适合其他 SIG，贴上相应标签。

• 涉及简短的技术讨论。

• 指派在该领域有专长的人进行审核、评论、拒绝等操作。

 

api-machinery sig 发现，始终如一地按照固定的时间表召开会议是分流工作成功的关键。他们发现，更频繁的小型会议比不频繁的大型会议要好。其他几个要点：

 

• 我们尝试平衡工作负荷，并询问人们是否可以在分配给他们之前接受一个 issue。

• 我们跳过已关闭的问题。

• 我们也跳过了cherrypicks，因为我们认为代码的变化是在原始PR中审查的。

• 我们确保SIG全体成员的参与，支持公司的多元化发展。

• 我们以此为契机，标明 "help needed", "good first issue"。

 

按集群生命周期划分的分类指南

 

SIG已经开发了一个分流页面，详细介绍了他们的流程，包括里程碑阶段。以下是2020年3月向 SIG 主席和领导小组所作的关于其进程的介绍。

 

 

第一步：查看新创建的未解决问题

 

Kubernetes 问题在 这里 列出。没有分类的 issue 是没有附加上 labels 的。 SIG 的 leads 应该指定至少一名 SIG 成员去作为新的 issue 的第一联系人。

 

搜索行为

 

GitHub 允许你过滤出 issue 和 pull request，从而帮助你发现需要分类的项目。为了方便起见，该表包含了一些预定的搜索：

Search	What it sorts
created-asc	Untriaged issues by age
needs-sig	Issues that need to be assigned to a SIG
is:open is:issue	Newest incoming issues
comments-desc	Busiest untriaged issues, sorted by # of comments
comments-asc	Issues that need more attention, based on # of comments

 

建议你优先筛选最旧的未标记 labels 的 issue 或者 pull requests

 

第二步：按类型分类问题

 

使用标签可以快速找到未解决问题。工程师可以添加适当的标签进行分类。

 

根据你的权限，关闭或评论那些被识别为支持请求、重复或者不可复现的错误，或者报告中缺少足够的信息。

 

支持请求（support request）

 

有些人错误地使用GitHub issue来提交 support request。通常，他们会在配置 Kubernetes 的某些方面寻求帮助。要处理此类问题，需要引导 author 使用 support request channels. 这时需要添加 triage/support 标签，将其引导到 support 组织架构，并关闭标签。

 

被废弃或错误放置的问题

 

关闭或评论它

 

Needs More Information

 

添加 triage/needs-information 标签表示 issue 需要更多信息，以便对其进行处理；回复或者关闭它。

 

Bugs

 

首先，通过尝试复现问题来验证问题是否为bug。

 

如果可以复现：

• 定义其优先级

• 进行快速的搜索，查看问题是否已经被报告。如果发现了重复的问题，则告知问题报告人，参考原有问题，并关闭重复问题。

 

如果不能够复现：

• 将你的发现与问题报告人沟通

• 如果双方都认同无法复现，请关闭该问题。

 

如果你需要更多信息以进一步解决此问题：

• 通过添加 lifecycle/needs-information 标签 告知问题报告者。

 

在所有情况下，如果你在20天内都未收到答复，请以适当的评论结束问题。如果你有权关闭其他人的问题，请先执行 /assign 操作将问题提交给自己，然后再执行 /close 操作。如果你不这样做，请在评论中留下你的发现。

 

Help Wanted/Good First Issue

 

为了确定专门针对新贡献者的问题，我们使用了 help wented 和 good first issue 标签。使用这些标签：

• 查看我们有关如何使用 Kubernetes 的特定准则

• 如果 issue 满足这些准则，你可以使用 /help 添加 help wanted 标签，使用 /good-first-issue 添加 good first issue 标签。请注意，添加 good first issue 标签也会自动添加 help wanted 标签。

• 如果问题具有这些标签但不符合准则，请要求将更多详细信息添加到 issue 中，或使用 /remove-help 或 /remove-good-first-issue 命令来删除标签。

 

Kind labels

 

通常，kind 标签由提交 issue 的人使用。如果 issue 的种类不对 （例如，被标记为 “ bug ” 的 “ support request ”）可以由他人进行纠正。double-checking 是一个好的方法。通过 issue templates 去引导人们选择正确的 issue 类型。

 

第三步：定义优先级

 

我们使用 GitHub 标签进行优先级排序。如果 Issue 没有 priority 标签，则表示尚未对其进行审核和确定优先级。

优先级标签	这是什么意思	例子
priority/critical-urgent	团队领导有责任确保这些 issue（在他们的领域）正在积极努力地解决。即是，放下你正在做的事情去处理这些 issue。这些 issue 应该在下一个版本发布前得到解决。	核心功能中对用户显而易见的错误   破坏了构建   严重的安全问题
priority/important-soon	必须为当前或不久的将来配备人员并投入工作-理想情况的是及时发布下一个版本。重要，但不会阻止发布。	[ XXXX ]
priority/important-longterm	从长远来看很重要，但目前可能没有人员或可能需要多次发布才能完成。不会阻止发布。	[ XXXX ]
priority/backlog	人们普遍认为这是一个不错的 issue，但是没有人可以在短期内对此进行研究。同时，社区贡献将是最受欢迎的，但是如果审核人员专注于较高优先级的问题（例如，在发布之前），可能需要一段时间才能对其进行审核。	[ XXXX ]
priority/awaiting-more-evidence	可能有用，但尚不足以真正完成它。	通常是占住潜在的好主意，这样它们就不会被完全遗忘，并且每次出现时都可以被引用或重复使用。

 

第四步：查找并设置正确的 SIG 来解决问题

 

各组件被划分为 Special Interest Groups（SIGs）。通过机器人找到合适的 SIG 来解决问题。

• 例如，在 comment 输入 /sig network 应自动添加 sig/network 标签

• 长命名的 SIG 需使用破折号： 例如， /sig cluster-lifecycle

• 请记住，这些命令必须在自己的行中，并且在 comment 的前面

• 如果你不确定 谁应该拥有 issue， 则仅引用 needs-sig 标签

• 如果你觉得 issue 应该保证被通知，通过 @ 提到对应的 SIG 团队，格式如下： @kubernetes/sig-<group-name>-<group-suffix>。

其中，<group-suffix> 可以是 bugs, feature-requests, pr-reviews, test-failures, proposals 其中一个。例如， @kubernetes/sig-cluster-lifecycle-bugs, can you have a look at this?

 

Self-Assigning

如果你认为自己可以解决这个 issue，请仅使用 /assigin 命令将 issue 分配给自己。如果你由于权限相关的原因无法自行分配，可以留下 comment，然后创建 PR。

 

第五步：跟进

 

如果在当前发布周期内没有为 issue 创建 PR

 

如果你看到任何由开发人员拥有但在30天内未创建 PR 的问题，则 Triage 工程师应联系问题所有者，并要求他们创建 PR 或 释放所有权。

 

如果已分配 SIG 标签，但30天内未采取任何措施

 

如果你发现分配了 SIG 标签的 issue，但在30天内没有任何动静或者讨论的迹象，请就此未解决问题反馈给 SIG group。另外，如果你觉得合适的话，可以考虑参加他们的定期会议以提出问题。

 

如果问题在90天后没有活动

 

发生这种情况时，fejta-bot 会将 lifecycle/stable 标签添加到该问题。你可以提前通过 /lifecycle frozen 标签来阻塞 bot 触发，或者通过 /remove-lifecycle stale 来移除标签。该 fejta-bot 在该 issue 添加 comment 中将包含额外的细节意见。如果你不采取任何步骤，则问题最终将自动关闭。

 

Footnotes

 

Support Requests: Channels

 

• User documentation and troubleshooting guide

• Stack Overflow and ServerFault

• Slack (registration)

• Discussion forums

User Support Response: Example

 

If you see support questions on [e-mail] or issues asking for support, try to redirect them to Stack Overflow. Example response:

Please re-post your question to [Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)

or our [Discussion Forums](https://discuss.kubernetes.io).

 

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 to 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 Kubernetes community use Stack Overflow and Discussion Forums to field

support requests. Before posting a new question, please search these for answers

to similar questions, and also familiarize yourself with:

 

  * [user documentation](https://kubernetes.io/docs/home/)

  * [troubleshooting guide](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/)

 

Again, thanks for using Kubernetes.

 

The Kubernetes Team