跳转到内容
搜索文档

内容评审

最后更新 查看 MarkdownAgent 设置

我们喜欢(并且很感激)在 GitHub 中开展工作,但这决不是一个完美的工具。

我们添加了几项符合人体工程学(ergonomic)的改进,以帮助我们分类筛选(triage)传入的工作、简化评审并实现自动化沟通。

分类筛选工作

为了帮助我们的作家分类筛选工作(并协助进行后端报告),我们实现了自动标记标签以及自动分配议题(issue)/拉取请求(pull request)负责人。

拉取请求

对于拉取请求,我们使用一个特定的 GitHub Action 来添加标签并分配代码所有者(codeowner)。

  • Label products(标记产品):我们为顶级产品文件夹添加标签,这有助于作家浏览传入的拉取请求并查看哪些拉取请求与他们相关。

  • Label size(标记大小):我们为拉取请求的修改规模添加标签,这有助于作家直观地看到修改的大小差异。这并不是一个完美的衡量标准,但我们通过被修改的行数来评估拉取请求的大小:

    label-size.tsts
    		switch (true) {
    			case changes <= 10:
    				label = "size/xs";
    				break;
    			case changes <= 100:
    				label = "size/s";
    				break;
    			case changes <= 500:
    				label = "size/m";
    				break;
    			case changes <= 1000:
    				label = "size/l";
    				break;
    			default:
    				label = "size/xl";
    				break;
    		}
  • 分配代码所有者:我们使用我们的 CODEOWNERS 文件,根据修改的文件自动将相关人员分配给拉取请求。这种自动分配有助于作家进行筛选和浏览,以查看哪些拉取请求与他们相关。

议题(Issues)

对于议题,我们使用类似的 GitHub Action 来添加标签并分配负责人。

由于议题中通常包含指向我们网站的链接,而不是仓库内的文件,因此我们的脚本会对此类议题进行处理。我们会提取议题描述字段中的关联链接,然后利用这些链接来分配作家(同样基于 CODEOWNERS)并添加产品标签。

简化评审

为了简化评审,我们使用了几项自动化功能来帮助解决评审员常见的痛点。

这会损坏什么吗?

我们在每次提交时都会运行一项必需的检查:CI

该检查可确保:

这需要谁来批准?

我们经常收到关于审批的疑问,尤其是涉及多个产品领域(或我们的组件)的拉取请求。

我们有 CI 的一个特定部分,能够发布一条评论,列出相关的代码所有者(codeowners)。

代码所有者评论

修改了什么?

我们使用 GitHub Action 为拉取请求上的每次提交发布预览构建(并在拉取请求上评论这些链接)。该 Action 确保了评审员能够确切地看到网站和内容在渲染后的外观(而不仅仅是在 GitHub 上查看修改后的 Markdown)。

我们目前正在逐步迁移到 Workers Builds,它原生提供了该功能。

根据反馈,我们还添加了一个链接修改前后的对照表,以帮助评审员在预览构建中轻松找到相关链接。

前后对照表

我还需要检查其他内容吗?

当拉取请求重命名或删除内容文件路径时,检查潜在的重定向是一件比较困难的事情。

我们有一个特定的 Action,能够发布一条评论来帮助评审员识别并检查这些路径。

GitHub Actions 重定向评论

自动化沟通

我们主要通过 no-response GitHub Action 来实现自动化沟通。

开源意味着我们接受来自任何人的议题和拉取请求!其中许多内容要么不言自明,要么有足够的上下文供我们跟进。

然而,那些缺乏足够上下文的内容往往非常令人头疼(特别是在像我们这样繁忙的仓库中)。作家必须要求提供更多细节,然后记住回来检查,有时还要重新索要更多细节,然后再回来检查。

为了帮助减轻这种精神负担,我们会提出问题,然后贴上 more-information-needed 标签。该标签会为作者启动一个 14 天的倒计时。如果他们做出了回应,该标签将被移除,对话即可继续。如果他们没有响应,该议题将自动关闭,并附带一条解释原因的评论

无响应评论

我们希望这一工作流能够在我们团队的需求与对贡献者的充分尊重之间取得平衡。

过期议题

我们有意避免使用 stale 工作流来关闭在特定时间段内处于非活跃状态的拉取请求或议题。

在我们看来,这种工作流引起的摩擦和沮丧情绪远多于它能解决的问题。仅仅因为某件事已经存在了一年,并不意味着它现在就失去了相关性。

这篇文档对您有帮助吗?