拉取请求评审流程

    Home Assistant 项目由多个 GitHub 仓库中的许多子项目共同组成， 这些项目一起构成了大家熟悉并喜爱的 Home Assistant。

    我们通过 GitHub Pull Request 收到大量社区贡献，这非常令人振奋， 我们也对此深表感谢。本页介绍我们的评审流程，帮助你了解提交 PR 后通常会经历什么。

    本页提供创建 Pull Request 及后续处理的一般建议和规范。它并不是 一份完整的 PR 教程，但其中大部分内容同样适用于参与其他开源项目。

    谁负责评审 PR？

    Home Assistant 是一个开源项目。项目中的大多数工作都由志愿者完成。 我们有一支核心开发团队，负责 Home Assistant 的整体架构，也负责合并 PR（他们同样是志愿者）。不过，评审 PR 的并不只有核心团队。

    任何人都可以参与 PR 评审，我们也非常鼓励这样做。🙏

    因此，在你提交 PR 后，也请考虑看看是否有其他开放中的 PR 可以帮忙。 无论是评审意见、改进建议，还是一句“我用……测试过，运行正常”， 我们都非常欢迎。与此同时，阅读他人的代码也是深入了解 Home Assistant 的好方法。

    在创建 PR 之前

    遵循架构决策。

    Home Assistant 项目的所有架构决策都记录在 ADR 目录中。 请在创建 PR 之前确认你的改动符合这些规则和规范，以免后续因为不符 合要求而需要额外调整。如果现有规则无法覆盖你的场景，可以先在 discussion 中发起讨论，达成必要结论后再提交 PR 评审。

    如何创建更容易通过评审的 PR

    并不存在“完美的 PR”，但你可以通过一些方式让评审过程更顺畅。 这不仅能减轻评审者负担，也能帮助你的改动更快合并，让最终用户更早 用上你的改进。

    1. 尽量让 PR 足够小。 一个 PR 最好只做一件事：重构一个点、修复一个问题、增加一个功能， 或修改文档中的一个主题。如果你要改多个内容，请拆成多个 PR。较小的 PR 范围更清晰、评审更快、冲突更少，通常也能减少来回修改轮次。

    2. 一次只改一类内容。 这和上一条类似，但更具体一些。你可能会顺手把附近一两行代码也“优化” 掉，但请尽量不要这样做，把这些内容放到单独的 PR 里。无关改动会分散 评审注意力，也更容易引发额外问题；而独立拆出的 PR 通常更容易快速评审 和合并。

    3. 在创建 PR 之前 先测试改动。 这听起来像常识，但我们仍然经常看到一些 PR 中包含根本无法运行的代码， 或者文档改动在页面上完全看不出来。这会浪费你和评审者双方的时间，也会 增加不必要的评审轮次。请至少先实际运行并验证你的改动，确认它们确实按 预期工作（对于文档来说，就是按预期呈现）。

    4. 确保你的 PR 基于最新的上游开发分支。 创建 PR 之前，请先同步上游最新改动。你在开发期间，上游仓库可能已经 发生变化，这可能导致合并冲突、测试失败，或你的改动与预期不符。

    5. 创建独立的（功能）分支。 每个 PR 都应基于一个单独分支（通常从开发分支拉出）。请为每个 PR 新建一个功能分支。这样既方便让开发分支持续与上游保持同步，也方便在 PR 合并后删除对应分支。

    6. 遵循 PR 模板，并写清楚标题和说明。 创建 PR 时，系统会提供一个 PR 模板。请尽量完整填写各项内容，并认真 编写清晰、准确、简洁的标题，同时在描述中详细说明改动内容。务必补充 改动动机（或使用场景），让评审者理解你为什么要这样改，以及为什么做出 某些设计决策。

    7. 依赖升级请单独提交 PR。 如果你需要升级某个依赖，尽量单独提一个 PR。这个 PR 中只应包含兼容性 调整或少量相关 bug 修复。如果还有依赖新版本才能实现的新功能，请放到后 续 PR 中再提交。这样做也能显著缩短 CI 评审周期，因为测试范围会限制在单 个集成内。 请确保 PR 描述中至少包含以下一种或多种信息：

      • 指向该版本及其中间所有版本发布说明的链接。
      • 指向该包变更日志的链接。
      • 指向当前版本与升级版本之间 Git(Hub) diff/compare 页面链接。 这些信息有助于我们审查上游变更，并判断这次升级是否按预期工作，或者是否 适合纳入例如 Home Assistant 的补丁版本发布。

    收到评审意见时

    当你的 PR 处于打开状态时，总会有人在某个时间点查看你的代码。评审者很 可能会留下意见，或者直接请求你修改某些内容。

    请务必明白，这些评审意见并不是针对你个人。 评审者不是在冒犯你， 也不是想让你难堪。他们是在帮助你把 PR 调整到可以合并的状态。和你一样， 他们也是志愿者，也都在努力让 Home Assistant 变得更好。大家的目标是一致的。

    无论你经验多丰富，总有可以向别人学习的地方。所以别排斥评审，试着主动 拥抱它。😄 如果有不明白的地方，不要害怕提问，也可以直接请求进一步解释。

    需要修改时，PR 会被标记为 Draft

    如果你的 PR 被请求修改，我们的机器人会自动将其标记为 draft。这表示该 PR 暂时还不适合继续评审或合并。

    Draft PR 能告诉其他评审者：这个 PR 仍在处理中，目前还不需要他们继续关注。

    完成所需修改后，你可以点击 “Ready for review” 按钮，将 PR 重新标记为 可评审状态：

    The ready for review button in the bottom of a PR in draft mode

    在点击 “Ready for review” 之前，请确认你已经处理完所有要求修改的项， 并且 CI 任务和检查都已通过。

    点击 “Ready for review” 后，PR 会恢复为正常状态，我们的机器人也会自动 通知之前提出修改请求的评审者，告诉他们 PR 已可继续处理。

    如何加快评审流程

    1. 构建 / CI 失败了？先把 PR 设为 Draft。 打开 PR 后发现构建失败？别担心，这种情况每个人都遇到过。如果你确认失败 与你的改动无关，可以保持 PR 打开状态；但如果失败是由你的改动引起的， 请在修复期间先将 PR 标记为 draft。这样可以避免评审者过早查看尚未准备好 的内容。

      Putting a PR in draft is something you can do too

    2. 持续关注 PR，并保持其最新状态。 即使 PR 暂时没人评审，也请主动关注。确保期间没有引入合并冲突（如果有， GitHub 会提示），如果一周都没有进展，也可以考虑同步最新开发分支。 这样在正式进入评审时，PR 会处于更容易处理的状态。

    3. 补充测试。 如果你在添加新功能，请务必补充测试；如果你在修复 bug，请补充能捕获该 问题的测试；如果你在重构代码，也请加上测试来确认没有引入回归。测试不仅 能证明你的代码当前可用，更重要的是帮助项目在未来持续稳定。虽然测试会让 评审内容变多，但也能帮助评审者更好理解你正在解决的问题。

    4. 回头再看一遍，继续打磨。 有时隔一段时间再看自己的代码，你会发现新的问题或还能改进的地方。在等 待评审期间，正是把 PR 打磨得更完善的好时机。

    5. 帮忙评审队列中的其他 PR。 想让整体评审流程更快，最好的办法就是亲自参与评审。你做的每一次评审， 都是在帮助整个社区加快节奏。而且，别人看到你的评审贡献后，也更可能回过 头来帮助你。

    不建议这样做

    • 不要就某个 PR 私下联系贡献者、代码所有者、核心团队成员或其他评审者， 也不要在 PR 中主动 @ 某人催评。你可能只是出于好意，但这容易被理解为 打扰或施压。相关通知会由机器人发送，请多一点耐心 :)

    • 不要在 PR 描述里写“请帮忙评审”之类的话。PR 本身就已经表达了这个意图 😉。 如有需要，机器人会通知合适的人选，请不要重复操作。

    • 不要提交依赖于其他未合并 PR 的新 PR。这样会在队列中制造一些当前无法处理 的 PR，增加额外负担。

    • 请控制自己同时打开的 PR 数量。我们没有硬性规定，但建议不要超过 5 个。 如果你有超过 5 个未合并 PR，我们可能会请你先关闭一部分，等已有 PR 合并后 再继续。

    • 如果你暂时不打算继续推进，就不要先打开 PR。若你在打开 PR 后无法继续处理， 请告诉我们并关闭它。关闭 PR 并不丢人；如果你是因为卡住了，也欢迎到我们的 Discord #devs 频道 寻求帮助。

    我的 PR 已经合并了！

    恭喜！🎉

    更重要的是：非常感谢你的贡献！❤️

    你刚刚让 Home Assistant 变得更好了。无论你改进的是代码、文档、测试、用户 体验还是社区协作方式，你都在帮助我们把 Home Assistant 打造成对每个人都更 友好的项目。

    继续保持这股势头吧！🚀 欢迎继续提交新的 PR，或者去帮助评审其他人的 PR。

    如果这是你的第一个 PR，也不用担心。我们保证，随着你不断参与，这个流程会 越来越顺手。

    常见问题

    1. 怎样才能让我的 PR 被合并？ 没有人能保证一个 PR 一定会被合并。我们有很多贡献者，也必须确保项目不被 改坏。我们会尽快评审你的 PR，但请保持耐心。如果你想提高推进速度，请阅读 上文关于如何加快评审流程的内容。

    2. 我的 PR 已经等了好几天，什么时候才会有人评审？ 这取决于仓库情况，也取决于很多因素。通常来说，修复 bug、提升代码质量、 体量较小、附带测试的 PR（以及这些特征的组合）会比新增功能类 PR 更容易优 先被处理。PR 的大小和复杂度也会影响响应速度，因为并不是每位评审者都愿意 或有能力接手复杂改动。想加快流程时，尽量让 PR 更小、更聚焦通常是有效方法。 此外，有些 PR 还需要特定领域的人来评审，例如涉及架构调整或必须经过代码所 有者批准的改动，这类情况等待时间通常会更长。

    3. 这么多小 PR，不会反而更低效吗？ 这是一个常见误解。表面上看，评审很多小 PR 好像工作量更大，但实际上反而 更高效。较小的 PR 更容易让更多人参与评审，也更容易被快速接手，所需时间 更短，与其他 PR 发生冲突的概率也更低。总体来说，小 PR 更容易得到高质量 评审，也更不容易引入新 bug，因为大型 PR 往往更容易遗漏细节。

    4. 机器人说我的 PR 快 stale 了，这是什么意思？ 如果一个 PR 长时间没有活动，机器人会自动将其标记为 stale；如果继续没有 动静，机器人还会自动关闭它。这可能意味着当前在等你修改，也可能是项目方 还没来得及评审。请先确认前者不是原因。如果你只是还在等待评审，可以直接 回复机器人，告诉它该 PR 仍然有效，它就不会继续推进关闭流程。同时，你也 可以考虑同步最新开发分支，确保你的改动跟上最新进展。

    5. 我有一个 PR 需要进入热修复 / 补丁版本，该怎么处理？ 正常创建 PR 即可，但请在 PR 描述中明确说明这是一个需要进入补丁版本的 hotfix。评审者会进一步确认这一点，并通过为该 PR 添加下一个补丁版本的 milestone，确保它进入对应发布流程。

    仓库特定说明

    我们的一些仓库还会在本通用指南基础上附加特定要求或额外规范。

    Home Assistant Core

    Home Assistant Core 仓库有较多要求和 规范，用于保障代码质量。下面这些开发者文档页面在你向 Core 仓库贡献时会很有帮助：

    Home Assistant Documentation

    如果你想了解如何参与文档贡献，请参见参与文档贡献。

    Home Assistant Frontend

    Home Assistant Frontend 在前端开发页面中提供了前端开发与贡 献相关指导。

    Home Assistant Intents

    构建语音助手是一项复杂工作，需要多个技术栈协同配合，因此请参考以下指南：

    还有问题怎么办？

    开发者文档里已经包含了大量信息，其中也包括更多与贡献和 Pull Request 相关 的内容。建议先使用页面右上角的搜索功能查找你需要的信息。

    但如果你仍然卡住，或者文档中没有回答你的问题，也欢迎到我们的 Discord #devs 频道提问。

    很多开发者都活跃在那里，通常都会有人愿意帮你一把。