介绍
在本教程中，你将通过“分析”执行单个拉取请求 Code Quality，从第一个注释到合并。 学习内容：
- 如何阅读有关拉取请求的 Code Quality 注释，并告知两种类型的查找。
- 如何使用查找的严重性标签来确定要修复的内容、要消除的内容以及顺序。
- 你在拉取请求中做出的选择如何影响仓库的评分、待办事项和合并门禁。
最后，你已解决示例拉取请求的每个阻塞查找，并将其与干净 Code Quality 检查合并，你将了解 你为什么 做出每个选择。
这是一次引导式演练，因此它更注重理解而非速度。 有关提交自动修复或忽略某项发现的基本步骤，请参阅配套操作指南：修复拉取请求中的代码质量问题
在您开始之前
- Code Quality 是在你参与的存储库上启用的。 请参阅“启用 GitHub Code Quality”。
- 存储库使用支持 CodeQL 的语言，以便生成基于规则的查找和分数。 有关支持的语言列表，请参阅 GitHub 代码质量。
- 你有一个针对默认分支的未合并拉取请求，其中至少有一个 Code Quality 发现项需要分类处理。 如果尚未准备好拉取请求，可以按照以下示例操作。
在本教程中，我们将使用一个贯穿始终的示例：某个对部分代码进行重构的拉取请求，如果按原样合并到默认分支，会引入若干代码质量问题。 系统已自动对该拉取请求运行了 Code Quality 扫描，并已将若干发现以评论形式提出。
为什么拉取请求是修复发现的问题的最佳位置
在拉取请求阶段无法解决的每个发现都会成为存储库积压工作中的一项操作项，技术债务通常比现在还清更贵。 现在，趁拉取请求还处于打开状态，你对代码的上下文和意图仍然记忆犹新，因此每项发现及其自动修复都能更快地评估、应用，或有把握地排除。
在拉取请求阶段解决发现的问题，意味着你的团队可以减少在修复工作与功能开发工作之间进行分流和权衡所花费的时间，并避免为了清理积压问题而额外发起拉取请求所带来的开销。
步骤 1：查找有关拉取请求的 Code Quality 注释
当您创建拉取请求时，Code Quality 会运行 两种类型的分析，并将结果作为评论发布。 打开拉取请求的“文件变更”选项卡，查看每条评论是谁留下的——评论作者会告诉你这属于哪种类型的问题。
-
基于规则的调查结果由 .
github-code-quality[bot]Code Quality 使用 CodeQL 根据一组规则扫描你的更改，并且每条评论都包含一个建议的自动修复。 -
由 AI 提供支持的发现 由 Copilot 发布。 如果您的组织拥有 Copilot 许可证，并且已为您的企业启用 AI 功能，Copilot 代码评审 会查找基于规则的分析可能遗漏的质量问题。 这些注释还包括建议的自动修复。
在我们的示例中，我们将查看来自 github-code-quality[bot]三个注释，因此它们是基于规则的发现。 在你自己的拉取请求里，你可能会看到这两种类型——在继续之前，先弄清楚哪种是哪种，因为严重程度标签（步骤 2）仅适用于基于规则的评论。
步骤 2：读取严重性标签以确定重要事项
每个基于规则的查找 github-code-quality[bot] 都带有严重性标签-“错误”、“ 警告”或 “注意”。 找到其中一条批注上的标签，并将其与此表进行核对。
| Severity | 定义 |
|---|---|
| Error | 表示可能导致 bug、故障或重大可维护性风险的高严重性问题。 |
| 警告 | 指示可能影响代码质量或可靠性的中等严重性问题，但并不立即至关重要。 |
| 备注 | 指示低严重性问题、轻微改进或建议。 这些发现对于代码的持续性健康状况和可维护性非常有用。 |
这个标签同时为你发挥两种作用：
- 它告诉你首先要修复什么。 严重性反映了规则在典型代码中的预期影响。 在我们的示例中，你应先处理 错误，然后处理 警告，并将 说明 视为可选的润色。
- 它可能决定是否可以完全合并。 仓库管理员或组织所有者可以将 Code Quality 配置为合并门禁。 例如，如果合并阈值为“警告及以上”，则必须修复或消除每个 警告和错误级别查找，然后才能合并（注意 发现不会阻止合并）。 同样，更严格的阈值可能需要在合并之前解决 所有 发现。
若要查看门禁是否生效，请滚动到拉取请求底部的 Checks 部分。 如果你的更改内容未达到所需阈值，你将看到一条合并被阻止的横幅提示：“合并被阻止：检测到代码质量问题。”
在我们的示例中，门禁规则设置为“警告及以上”，因此会显示该横幅：错误和警告会阻止合并，而注释不会。 这说明在合并此拉取请求之前必须清除的内容。
如果合并块横幅未指定严重性级别，则必须清除 所有 结果才能合并拉取请求。
步骤 3：解决每个发现问题
对于每个发现，请确定它是否适用于你的代码，如果适用，如何修复它。 这会让你采取以下三种操作中的一种。
| Assessment | 建议的操作 | 注释 |
|---|---|---|
| 发现是合法的，建议的修复看起来正确 | ||
| 应用自动修复建议 | 单击 提交建议 不会使用 AI credits，并且基于规则的自动修复不需要 Copilot 许可证。 | |
| 该问题确实存在，但你想一次性修复多个，或者建议的修复方案需要调整 | ||
委托给 Copilot- 在注释中提及 @copilot 将工作交给云代理。 | ||
| Copilot响应 👀，启动新的代理会话，并将必要的修复推送到拉取请求的分支 | 需要 Copilot 许可证，并消耗 AI credits。 | |
| 例如，此发现不适用：它是测试代码、有意为之的模式，或属于误报 | 单击忽略发现并提供原因 | 你将能够合并你的拉取请求，但发现的问题会显示在仓库待办事项中，并且在今后的拉取请求中也会出现。 |
将这一做法应用到你自己的拉取请求中，并按严重程度顺序处理。
在我们的示例中：
- 错误级和警告级的问题项确实是真正的缺陷，而且建议的自动修复看起来也很合理，因此我们采纳这些自动修复建议。 这些发现的问题在解决后将不再计入阻塞计数。
- 注记级发现项会标记出相邻测试辅助程序中的次要模式。 这是有意的，所以我们以“在测试中使用”等原因消除它。
- 还有其他几个 注释级发现。 我们不是逐条处理每个自动修复建议，而是添加评论：“
@copilot，修复所有剩余的 Note 级别问题”。 我们在存储库的Copilot”选项卡中跟踪**** 进度，并在请求准备就绪时查看推送到拉取请求的提交。
步骤 4：确认拉取请求已取消阻止（可选）
如果您确实存在阻塞性问题，在修复或忽略相关问题后，请返回到拉取请求底部的 “检查” 部分。
在我们的示例中，解决 “错误 ”和“ 警告 ”结果后，合并块横幅将消失。 你的拉取请求现在已可合并。
如果该横幅仍然存在，则表示仍有严重级别达到或高于阻塞级别的发现项处于打开状态。
步骤 5：解决来自 Copilot 的 AI 支持的调查结果
如果你的组织拥有 Copilot 许可证，且你的企业已启用 AI 功能，你还会看到由 Copilot 发布的评论。 这些是在步骤 1 中引入的AI 生成的发现，这些发现来自Copilot 代码评审，而非github-code-quality[bot]。
如果基于规则的发现结果是将您的更改与一组固定的 CodeQL 规则进行匹配，Copilot 代码评审 则会推断您的代码意图。 它能发现那些无法归入某一具体规则的质量问题，因此，相较于替代基于规则的评注，它更适合作为对这类评注的有益补充。
这些发现不带有“错误”、“警告”或“注意”的严重性标签。 由于您在步骤 2 中看到的合并门禁仅计算基于规则的发现结果的严重性，因此 AI 驱动的发现结果本身不会阻止您的拉取请求。 这并不意味着它们是可选项；结合上下文来解决这些问题，仍然是防止质量问题进入默认分支的最佳方式。
可以使用步骤 3 中使用的相同三个选项解决 AI 驱动的查找：
- 采用自动修复建议。 每条评论都包含一个建议的修复方案。 如果当前内容正确无误，请单击提交建议。 应用自动修复不会消耗 GitHub AI Credits。
- 委托给 Copilot- 在注释中提及
@copilot将工作交给云代理。 Copilot与 👀 交互，开启新的代理会话，并将必要的修复推送到拉取请求的分支。 此选项需要Copilot许可证，并且会消耗GitHub AI Credits。 - 解决注释。 如果它不适用于代码，请单击“ 解析”。
这与代码健康状况的其他部分有何关联
你刚刚处理完的拉取请求只是更大局面中的一部分：
- 分数。 存储库的可靠性与可维护性分数是从默认分支上的发现计算得出的。 在合并之前解决调查结果是阻止这些分数偏离的方式。 请参阅“指标和评分参考”。
- 积压工作。 在拉取请求中未修复的任何问题，都会进入默认分支上的待处理发现项积压列表。 逐步消化这些积压工作本身就是一门学问。 请参阅“提高存储库的代码质量分数”。
- 合 规。 当某一类发现结果确实绝不能进入默认分支时，“要求提供代码质量结果”规则集可帮助仓库管理员和组织所有者将这一决策设定为合并门禁。 请参阅“解决拉取请求中的阻塞”。
最健康的团队会将这三者结合起来：在拉取请求阶段有针对性地进行分流和修复，定期处理积压事项，并在合并前关口强制执行阈值。
Troubleshooting
- 我看不到任何 Code Quality 评论。 扫描可能仍在运行，更改可能未触及受支持的语言，或者没有任何发现。 确认 Code Quality 已启用，并给出检查（称为“CodeQL - 代码质量”）完成的时间。 请参阅“启用 GitHub Code Quality”。
- 我只看到来自
github-code-quality[bot]的评论，从来没看到来自 Copilot 的评论。 AI 生成的发现结果需要 Copilot许可证，并且需要为您的企业启用 AI 功能。 如果没有它们，你将只看到基于规则的发现。 - 我看不到代码质量结果的自动修复。 自动修复生成会消耗 GitHub AI Credits。 你的组织可能已耗尽其每月预算 AI credits。
- 合并块横幅无法清除。 至少有一个发现在阻塞严重性以上仍然处于打开状态。 如果在合并块横幅中看不到定义的严重性级别，这意味着存储库使用的是最严格的代码质量阈值，这要求在合并之前解决 所有 发现。 请参阅“解决拉取请求中的阻塞”。
结束语
在本教程中，你已逐条处理拉取请求中的 Code Quality 评论，使用严重程度来确定修复优先级，并在合并拉取请求之前审慎地解决每一项发现的问题。 通过将每个问题及其自动修复都视为一个结合上下文的小决策，你避免了代码质量债务进入默认分支。
后续步骤
- 对现有积压工作应用相同的思维： 提高存储库的代码质量分数。
- 了解结果如何转化为分数，以便你可以测量工作的影响： 指标和评分参考。