自动化和分类流程

本文档详细概述了我们用于管理和分类问题及拉取请求的自动化流程。我们的目标是提供及时的反馈，并确保贡献得到高效的审查和集成。了解这些自动化流程将帮助您作为贡献者知道会发生什么，以及如何最好地与我们的存储库机器人进行交互。

指导原则：问题和拉取请求

首先，几乎所有的拉取请求（PR）都应该链接到一个相应的问题。问题描述了“什么”和“为什么”（bug或功能），而 PR 则是“如何”（实现）。这种分离有助于我们跟踪工作、确定功能优先级并维护清晰的历史背景。我们的自动化围绕这一原则构建。

---

详细的自动化工作流程

以下是我们存储库中运行的具体自动化工作流程的细分。

1. 当您打开一个问题时：自动化问题分类

这是您在创建问题时会首先交互的机器人。它的工作是进行初步分析并应用正确的标签。

• 工作流文件: .github/workflows/gemini-automated-issue-triage.yml
• 运行时间: 问题创建或重新打开后立即运行。
• 作用:
  • 它使用 Gemini 模型根据一套详细的指南分析问题的标题和正文。
  • 应用一个 area/* 标签: 将问题分类到项目的某个功能区域（例如，area/ux、area/models、area/platform）。
  • 应用一个 kind/* 标签: 识别问题的类型（例如，kind/bug、kind/enhancement、kind/question）。
  • 应用一个 priority/* 标签: 根据描述的影响分配优先级，从 P0（关键）到 P3（低）。
  • 可能应用 status/need-information: 如果问题缺少关键详细信息（如日志或重现步骤），它将被标记为需要更多信息。
  • 可能应用 status/need-retesting: 如果问题引用的 CLI 版本比当前版本旧六个版本以上，它将被标记为需要重新测试。
• 您的操作:
  • 尽可能完整地填写问题模板。您提供的细节越多，分类就越准确。
  • 如果添加了 status/need-information 标签，请在评论中提供所需的信息。

2. 当您打开一个拉取请求时：持续集成 (CI)

此工作流程确保所有更改在合并前都符合我们的质量标准。

• 工作流文件: .github/workflows/ci.yml
• 运行时间: 在拉取请求的每次推送时运行。
• 作用:
  • Lint: 检查您的代码是否符合我们项目的格式和样式规则。
  • Test: 在 macOS、Windows 和 Linux 上，以及在多个 Node.js 版本上运行我们完整的自动化测试套件。这是 CI 过程中最耗时的部分。
  • 发布覆盖率评论: 所有测试成功通过后，机器人将在您的 PR 上发布一条评论。该评论提供了您的更改在测试覆盖率方面的摘要。
• 您的操作:
  • 确保所有 CI 检查都通过。当一切成功时，您的提交旁边会出现一个绿色的勾号 ✅。
  • 如果检查失败（一个红色的 "X" ❌），请点击失败检查旁边的“详细信息”链接查看日志，找出问题所在，然后推送一个修复。

3. 拉取请求的持续分类：PR 审计和标签同步

此工作流程会定期运行，以确保所有打开的 PR 都正确链接到问题，并具有一致的标签。

• 工作流文件: .github/workflows/gemini-scheduled-pr-triage.yml
• 运行时间: 每 15 分钟在所有打开的拉取请求上运行。
• 作用:
  • 检查链接的问题: 机器人会扫描您的 PR 描述，查找链接到问题的关键字（例如，Fixes #123、Closes #456）。
  • 添加 status/need-issue: 如果找不到链接的问题，机器人将向您的 PR 添加 status/need-issue 标签。这是一个明确的信号，表明需要创建一个问题并进行链接。
  • 同步标签: 如果 确实 链接了问题，机器人会确保 PR 的标签与问题的标签完全匹配。它会添加任何缺失的标签，删除任何不属于的标签，如果 status/need-issue 标签存在，它也会将其删除。
• 您的操作:
  • 始终将您的 PR 链接到问题。这是最重要的一步。在您的 PR 描述中添加一行，如 Resolves #<issue-number>。
  • 这将确保您的 PR 被正确分类，并顺利进入审查流程。

4. 问题的持续分类：计划性问题分类

这是一个备用工作流程，用于确保没有问题会被分类流程遗漏。

• 工作流文件: .github/workflows/gemini-scheduled-issue-triage.yml
• 运行时间: 每小时在所有打开的问题上运行。
• 作用:
  • 它会主动查找那些完全没有标签或仍然带有 status/need-triage 标签的问题。
  • 然后，它会触发与初始分类机器人相同的强大 Gemini 分析，以应用正确的标签。
• 您的操作:
  • 通常您不需要做任何事情。此工作流程是一个安全网，可确保每个问题最终都能被分类，即使初始分类失败。

5. 发布自动化

此工作流程负责打包和发布新版本 Gemini CLI 的过程。

• 工作流文件: .github/workflows/release-manual.yml
• 运行时间: 对于“夜间”版本，按每日计划运行；对于官方补丁/次要版本，手动运行。
• 作用:
  • 自动构建项目，增加版本号，并将软件包发布到 npm。
  • 在 GitHub 上创建相应的发布，并附带生成的发布说明。
• 您的操作:
  • 作为贡献者，您无需为此流程执行任何操作。您可以放心，一旦您的 PR 合并到 main 分支，您的更改将包含在下一个夜间版本中。

希望这个详细的概述对您有所帮助。如果您对我们的自动化或流程有任何疑问，请随时提出！