拉取请求审查流程
Home Assistant 项目由许多较小的项目组成，这些项目分布在多个 GitHub 代码库中，共同构成了我们大家所知道和喜爱的神奇的 Home Assistant。
我们通过 GitHub 拉取请求收到许多贡献，这真是太棒了。我们对此非常感激。此页面描述了我们的审查流程，以便您在提交 PR 时了解可以期待什么。
本页面提供了创建拉取请求的常规提示和指南，以及如何处理这些请求。它不是创建 PR 的完整指南；然而，本页面的大部分内容适用于为任何开源项目做贡献。
谁负责审查 PR？
Home Assistant 是一个开源项目。我们项目中的大多数工作都是由志愿者完成的。我们有一个核心开发团队，负责 Home Assistant 的整体架构，并负责合并 PR（也是志愿者）。然而，他们并不是唯一审查 PR 的人。
每个人都可以帮助审查 PR，我们鼓励任何人这样做。🙏
因此，当您打开 PR 时，请考虑查看是否有开放的 PR 您可以帮助。任何审查评论、改进建议，甚至只是 "我使用...进行了测试并且它能工作" 都会受到非常感激。此外，查看他人的代码是学习更多有关 Home Assistant 的绝佳方式。
在创建 PR 之前
遵守架构决策。
与 Home Assistant 项目相关的所有架构决策都记录在 ADR 文件夹 中。在创建 PR 之前，请确保遵循这些规则和指南，以避免因您的 PR 未遵循这些规则而导致的后续调整。如有需要，可以进行新的 讨论，以便在提交 PR 进行审查之前做出必要的决策。
创建完美的 PR
没有完美的 PR，但您可以采取一些措施使审查您的 PR 更容易。这不仅会帮助审阅者，也会帮助您作为贡献者更快地合并更改，并使最终用户更快获得您的改进。
-
使您的 PR 尽可能小。 PR 应仅重构一件事，修复一件事，添加一项功能，或调整文档中的单个主题。如果您想更改多个内容，请创建多个 PR。较小的 PR 范围较小，审查所需时间更少，发生冲突的可能性更小，并且通常需要更少的审查迭代。
-
一次只更改一件事。 这与之前的观点相同，但更具体。改善您附近注意到的那一两行代码是很诱人的，但请不要这样做。将这些放在一个单独的 PR 中。在您的 PR 中的无关更改会分散注意力，通常会导致问题。相比之下，在独立的 PR 中，这将是快速且简单的审查和合并。
-
在创建 PR 之前测试您的更改。 这听起来很明显，但我们经常看到包含不可能工作的代码或在生成页面上不可见的文档更改的 PR。对于您和审阅者来说，当然这是件浪费精力的事情；这增加 了一次不必要的审查迭代。确保您至少运行并实际测试您的更改。确保它们按预期工作（或者在文档的情况下：外观）。
-
确保您的 PR 基于最新的主上游分支版本。 在创建 PR 之前，请确保拉取最新的上游更改。在您编写更改时，上游可能已经发生变化。这可能会导致合并冲突、测试失败，或者您的更改无法正常工作。
-
创建一个（功能）分支。 当您创建 PR 时，它是基于一个分支（通常是主分支）。您必须为每个创建的 PR 创建一个新功能分支。这使得更新主分支与上游分支更容易，并且在 PR 被合并后更容易删除该分支。
-
遵循 PR 模板并添加清晰的标题和详细的描述。 当您打开 PR 时，将提供一个 PR 模板。使用模板并尽可能多地填写字段。花时间写一个好的、清晰的、简明的标题，并添加您更改的详细描述。务必在 PR 中添加动机（或用例），以便审阅者能理解您为什么进行此更改（或为什么做出某些决策）。
-
在单独的 PR 中更新依赖项。 当您需要提升依赖项时，请尝试在单独的 PR 中进行。仅应在 PR 中包括兼容性代码调整或小的相关 bug 修复。有关更新依赖项的新功能，可以在后续中添加。这也将使 CI 迭代在审查新功能或较大的 bug 修复时运行得更快，因为它将测试限制为单个集成。确保 PR 描述中包含以下至少一个（或多个）内容：
- 该软件包版本的发行说明链接，以及所有之间的版本。
- 该软件包的变更日志链接。
- 从当前版本到提升版本的 Git(Hub) diff/比较视图链接。 这使我们可以审查上游更改，这对于决定此更改是否按预期工作和/或是否可以将其包含在 Home Assistant 的补丁发布中是必要的。
接收审查评论
当您的 PR 打开时，某人会在某个时刻查看您的代码。审阅者可能会对您的代码有一些评论，甚至会提出一些更改请求。
请非常注意，这些审查评论不是针对个人的。 审阅者并不是为了侮辱您或让您感到不好。他们是为了帮助您改善您的 PR，以便它能够被合并。就像您一样，他们也是志愿者，他们试图帮助使 Home Assistant 成为最佳。我们都有相同的目标。
无论您的经验如何，总有从他人那里学习的东西，所以不要讨厌它，而要接受它。😄 不要害怕提问或要求澄清。如果您不理解某事，请询问！
当需要更改时 PR 被标记为草稿
如果已经请求对您的 PR 进行更改，我们的机器人会自动将您的 PR 标记为草稿。这意味着该 PR 当前尚未准备好合并或进一步审查。
草稿 PR 会告诉其他审阅者查看所有 PR 列表时，该 PR 目前正在进行中，尚未需要他们的注意。
一旦您做出了请求的更改，可以通过单击 “准备好审查” 按钮再次将 PR 标记为准备审查：
在点击 “准备好审查” 按钮之前，请确保您已经解决了所有请求的更改，并且我们所有的 CI 作业和检查都成功通过。
一旦您点击了 “准备好审查” 按钮，PR 将恢复到正常状态，我们的机器人将自动通知请求更改的审阅者，该 PR 已准备就绪！
加快审查流程
-
构建/CI 失败？将您的 PR 标记为草稿！ 打开 PR 后，构建失败？别担心，这对我们所有人来说都是常有的事。如果您确定失败与您的更改无关，您可以保持 PR 打开。然而，如果失败与您的更改相关，您应该在解决它时将 PR 标记为草稿。这将防止审阅者在该 PR 准备好之前查看它。
-
监控您的 PR 并保持其最新。 即使您的 PR 未被审查，您也应积极监控它。确保在此期间没有引入合并冲突（如果是这样，GitHub 会告诉您），并且在一周不活动后，可能需要将其重置到最新的开发分支。这确保了您的 PR 在审查流程开始时已准备就绪。
-
添加测试。 如果您添加新功能，请确保添加测试。如果您修复了 bug，请确保添加一个可以捕捉到该 bug 的测试。如果您正在重构代码，请添加测试以确保重构没有破坏任何东西。测试有助于显示您的代码按预期工作，但更重要的是，确保未来一切保持正常工作。尽管测试会增加更多代码供审查，但它也有助于审阅者以不同的方式理解您正在解决的问题。
-
重新审视、调整并优化 到完美。 有时，稍后回顾自己的代码会教会您新事物并帮助您发现不完美或问题。在等待审查时，确保您的 PR 尽可能好是个不错的时机。
-
帮助审查队列。 加快审查流程的最佳方法就是帮助其他人进行审查！您所做的任何审查工作都有助于加快每个人的审查流程。此外，其他人可能会注意到您的审查并回报帮助。
不要做的事情
-
请不要直接联系贡献者、代码所有者、核心团队成员或其他审阅者，或在 PR 中标记/提及他们以请求审查。虽然您可能是以友好的方式进行的，但这可能被视为令人烦恼或要求过高。相反，我们的机器人将处理相关人员的提醒，并且：请多点耐心 :)
-
请不要在 PR 描述中请求审查。这是多余的，因为 PR 本身已经很清楚这一点 😉。我们的机器人会在需要时通知适当的人；请避免自己这样做。
-
请勿提交依赖于仍处于开放/未合并状态的其他拉取请求的新拉取请求。这会在队列中创建不必要的拉取请求，无法处理。
-
限制您拥有的开放拉取请求数量。我们没有严格的规定，但建议将其限制为 5。如果您有超过 5 个开放的 PR，我们可能会要求您关闭其中一些，直到一些其他的被合并。
-
如果您打算不再继续处理一个 PR，请不要打开它。如果您在打开 PR 后无法继续处理，请告诉我们并关闭它。关闭 PR 并没有什么可耻的；但是，如果是因为您被卡住了，请随时在我们的 Discord 聊天 中的 #devs 频道 请求帮助。
我的 PR 已合并！
恭喜！🎉
最重要的是：非常感谢！❤️
您刚刚让 Home Assistant 成为一个更好的地方。您帮助我们改善了代码、文档、测试、用户体验或社区。您帮助我们为每个人提升了 Home Assistant 的质量。
保持这一势头！🚀 随时打开另一个 PR 或帮助审查其他 PR。
如果这是您的第一个 PR，请不要担心，我们保证，每次经过这个过程都会变得更容易。
常见问题
-
我怎么才能让我的 PR 被合并？ 没有保证您的 PR 会被合并。我们有很多贡献者，我们必须确保不破坏任何东西。我们会尽快审查您的 PR，但请保持耐心。如果您想加快这个过程，请阅读上面的部分，了解如何加速审查流程。
-
我的 PR 已经等待审查几天了，什么时候会被审查？ 根据代码库的不同，审查您的 PR 可能需要一些时间。这取决于许多因素。例如，修复 bug、改善代码质量、较小的 PR，或提供测试的 PR（以及这些的组合）通常优先于添加新特性的 PR。PR 的大小和复杂性也可能是一个因素，因为这意味着较少的审阅者愿意或能够接手您的 PR。您始终可以考虑尝试将您的 PR 制作得更小、更专注，以加快审查流程。一些其他的 PR 可能需要或需要某个具有特定知识的人来进行审查（例如架构更改或需要代码所有者批准的更改），这可能会导致更长的等待时间。
-
所有这些小 PR 不是超级低效吗？ 这是一种常见的误解。虽然审查很多小 PR 可能似乎是一项庞大的工作，但实际上这是更有效的。较小的 PR 对更大群体的人来说更容易审查，这意味着更多的人可以参与审查的帮助。它们在较短时间内被提取的可能性更大，也更不可能与其他 PR 冲突。一般来说，审查较小的 PR 会获得更好的审查，并且不太可能导致新的 bug，因为在大的 PR 中更容易忽视某些东西。
-
机器人说我的 PR 正在变成陈旧，那么这意味着什么？ 该机器人将在一段时间的不活动后自动将 PR 标记为陈旧。如果 PR 仍然不活动，它将关闭该 PR。这可以意味着该 PR 正在等待您的更改或我们项目的审查。请确保不是前一种情况，如果您正在等待审查，只需评论一下。在回应机器人时，机器人将知道事情并未陈旧并将放慢速度。与此同时，可能是一个好主意，将您的 PR 重新基于最新的开发分支，以确保您与最近的变化完全同步。
-
我有一个 PR 应该包含在热修复/补丁发布中，我该怎么办？ 就像正常创建 PR 一样创建，并在 PR 描述中明确说明该 PR 是需要包含在补丁发布中的热修复。审阅者将对此进行二次检查，并确保在下一个补丁发布中通过为 PR 标记下一个补丁里程碑来包含它。
仓库特定信息
我们的一些仓库有特定的要求或指南，这些要求或指南适用于此一般指南之上。
Home Assistant Core
Home Assistant Core 仓库有很多要求和指南，以确保代码的质量。以下我们开发者文档中的页面可能在为我们的 Core 仓库创建贡献时有帮助：
Home Assistant 文档
文档 在贡献时还有额外的指南需要考虑。我们主要遵循微软写作风格指南，并对 YAML 配置样式有一些额外的指导。
Home Assistant 前端
Home Assistant 前端 对于在前端开发和贡献的指导可参见 前端开发页面。
Home Assistant 意图
构建语音助手是一项复杂的任务。它需要很多不同的技术协同工作，因此有一些指南需要查看：
帮助？！我还有更多问题！
开发者文档有很多信息，甚至更多有关贡献和拉取请求的信息，因此请务必使用页面右上角的搜索功能查找您所需的内容。
然而，您可能仍然卡住了或有问题未在文档中回答。在这种情况下，欢迎在我们的 Discord 聊天的 #devs 频道 中提问。
我们许多人都在那里，永远有人愿意帮助您。