拉取请求提交和审查指南

我们希望 MDN Web Docs 成为一个我们都能引以为豪的友好、温馨的社区。所有参与者必须遵守我们的 行为准则，这意味着遵守 Mozilla 的社区参与指南。在打开拉取请求、撰写审查评论、与拉取请求作者或其他社区成员互动时，请保持礼貌和建设性。如果您或其他人遇到可能违法或让您感到不安全、不受欢迎或不舒服的行为，我们鼓励您 报告它。

在开始在 MDN 上工作之前，请仔细阅读以下建议和指南。

拉取请求必须解决或部分修复现有问题。我们有此限制的原因是为了避免您开始其他人可能已经在进行的任务。在您要贡献的 MDN 代码库 中搜索问题和拉取请求，并确认您要开始的工作尚未进行。在寻求为 MDN 项目做贡献时，您会发现自己处于以下情况之一

• 如果您想为该项目做出贡献，您可以在任何 MDN GitHub 代码库 （例如，mdn/content 问题）中的“问题”下找到任务，以及我们的 公共 GitHub 项目看板。确保该问题没有分配给任何人，并且没有人已经为该任务打开了拉取请求。标有 good first issue 的问题是一个很好的起点。
• 如果您在 MDN 上发现了问题，您应该首先打开一个问题。问题需要维护者的回复才能开始工作，这样您才能知道拉取请求解决的问题是有效的，并且您的拉取请求会被接受。有关问题的更多信息，请参阅我们的 社区 GitHub 问题页面。
• 如果您想建议新的内容或新功能，请通过“新内容或功能建议”GitHub 问题模板 提交建议。

如果您不确定从哪里开始，请访问 Discord 服务器 并寻求反馈。

当您准备好打开拉取请求时，请遵循以下指南

• 拉取请求应该简短且专注于一个问题：如果可能，将相关的更改分组到多个小的拉取请求中。如果拉取请求变得太大，审阅者可能会将其关闭，并要求您为属于一起的每个逻辑更改集提交拉取请求。
• 添加更改说明：尽可能提供拉取请求的上下文和理由。
• 添加您要关闭的问题的链接：在拉取请求说明中，如果它完全解决了问题，则添加“修复”，如果它是相关问题，则添加“与之相关”。有关在拉取请求中链接到问题的更多信息，请参阅 GitHub 文档。
• 添加“依赖于”以及指向依赖项的链接，如果存在必须先合并的拉取请求（例如，其他代码库中的代码示例）。
• 将代码示例更改与内容更改一起添加：这对于确保正确提供更新的示例非常重要。如果您正在进行影响示例使用方式的内容更改，则相关的代码示例也应进行更新。
• 添加审阅者：如果您已经知道谁应该审查您的拉取请求，您可以添加审阅者，例如团队成员或主题所有者。
• 不要只进行语法更改：MDN Web Docs 包含技术文档；除非语法错误，否则您不应建议散文风格更改。
• 不要不必要地在遵循特定格式风格的页面上添加或删除换行符。
• 不要启用自动合并。

• 处理作为 GitHub Actions 运行的自动测试（请参阅 .github/workflows）的CI 故障。如果其中一个或多个测试失败，您有责任尝试解决这些问题。如果您不知道如何解决根本问题，请寻求帮助。
• 解决与主分支的合并冲突；您有责任解决这些问题。您可以通过将 mdn/main 分支合并到您的分支中来完成此操作。有关更多信息，请参阅 GitHub 文档，了解如何 使您的分支保持最新。
• 对反馈做出响应。这意味着准备好根据审查对拉取请求进行更改。如果审查已经进行，但未进行更改，则拉取请求可能会被关闭。
• 在审查过程中要有耐心。MDN 组织收到了大量的拉取请求，团队可能需要时间来审查您的贡献。
• 不要重新打开已关闭的拉取请求。如果您必须创建一个新的拉取请求，它可以引用已关闭的拉取请求。

当您基于 CODEOWNERS 文件打开拉取请求时，审阅者会自动分配，但如果您希望请求特定的人员进行审查，您可以 手动请求审查。我们还在拉取请求上使用自动标签来帮助我们进行分类。维护者可以根据上下文，进一步对拉取请求进行分类，并添加任何其他标签，例如 needs-info 或 on-hold，如果需要。

如果您想审查拉取请求，但未被列为审阅者，您可以将自己添加为审阅者。在开始审查之前，最好先通过在拉取请求中发表评论来与现有审阅者核实。

MDN Web Docs 团队使用审阅者和分配者来跟踪拉取请求的状态。

• 审阅者是对拉取请求中的更改进行评估并为作者提供反馈的人员。
• 分配者是负责确保拉取请求不被阻塞的人员。并非所有拉取请求都有分配者，但如果有，他们负责确保拉取请求取得进展。分配者通过合并、关闭或自己承担解除阻塞工作来帮助工作达成结论。

拉取请求的评审者或分配者负责合并更改。

在开始评审之前，请查看拉取请求描述，确保没有指定人员需要评审。确保所有持续集成 (CI) 任务都已成功完成，并且没有合并冲突。

如果任何任务失败或存在合并冲突，请与作者沟通；解决这些问题是他们的责任。您可以将作者设置为 **分配者**，表明在开始评审之前需要作者的关注。要为作者留下寻求帮助的机会，特别是对于项目的贡献者而言。

在拉取请求中的更改方面，内容和散文必须符合 MDN 写作风格指南，示例代码必须遵循 代码风格指南.

当您评审拉取请求时，您应该

• 添加评论到拉取请求中，让作者知道您已经注意到拉取请求，并将开始评审。这样做是为了避免其他人不必要地同时开始评审拉取请求的情况。
• 将评审范围限制在拉取请求中的更改。打开一个后续问题或拉取请求来解决拉取请求未涵盖的其他改进。
• 寻求帮助 并添加 review-help-needed 标签，如果您需要技术帮助进行评审。
• 关闭包含无关更改的拉取请求，如果它过于复杂或包含多个无关更改。在这种情况下，请拉取请求作者将他们的更改提交为较小的块。
• 请求负载均衡 如果您的工作量很大，并且没有带宽进行评审。标记 @core-yari-content 团队并询问其他人是否可以介入。
• 除非“取决于” 拉取请求首先被合并，否则不要合并。
• 不要合并测试失败的拉取请求。 这是很好的 开源礼仪，以保持 main 分支稳定，以避免对贡献者、维护者和自动化流程造成干扰。不稳定的 main 分支会阻止所有其他拉取请求，并使其他人难以评审和合并贡献。此外，监视存储库的贡献者会收到大量通知，而由测试失败引起的无用噪声可能会令人沮丧。如果您不确定如何修复测试失败，寻求帮助 或将拉取请求分配给其他人。

如果拉取请求看起来不错，除了少量错别字或其他小问题，您可能希望直接修复问题。您可以这样做，前提是拉取请求 已设置为允许更改。建议使用 带有建议的评论 来修复小问题，因为它们可以批量提交并一次性提交。

提交评审时，您有三个选项，批准、评论或请求更改。以下部分解释了何时使用每个选项。

当您提供的反馈需要由作者处理，并在拉取请求被批准和合并之前由评审者重新评审时，使用请求更改选项。

评论

当您的反馈不是关键性的，并且不需要重新评审时，使用评论选项。简而言之，您信任作者和其他评审者会做出明智的判断。

批准

当一切看起来都很好，并且从您的角度来看准备合并时，使用批准选项。提交评审后，如果没有任何其他评审者或任何未解决的评审评论，您可以安全地合并拉取请求。

如果您遇到问题该怎么办

如果您不理解内容更改，或者觉得它过于庞大复杂，无法处理，请不要惊慌！一个好的起点是向拉取请求作者寻求信息以帮助您。

很少有必要在没有任何警告的情况下评审一个大型复杂的内容更改。但是，如果确实发生了这种情况，拉取请求描述应该链接到一个解释背景信息的问题。

如果您仍然不确定，或者您认为内容可疑，请联系 MDN Web Docs 团队并寻求帮助。

本部分提供有关预期周转时间的详细信息，包括在回复评审评论时（如果您是拉取请求作者）和在评审拉取请求时（如果您是评审者）的详细信息。

• 评审：拉取请求评审者应该能够在 2 周或更短的时间内评审更改。在拉取请求打开后的 2 周内，评审者可以
  • 留下关于他们何时可以开始评审拉取请求的评论
  • 请求技术或资源帮助
• 解决请求的更改：拉取请求作者应该能够在 4 周或更短的时间内回复或修复评论。如果拉取请求作者无法在该时间内回复或修复评审评论，评审者可以执行以下操作之一
  • 提交更改并合并拉取请求
  • 关闭拉取请求

MDN 内容存储库中的一些拉取请求与浏览器供应商或组织的特定工作相关，这些工作具有定义的作者和评审者。在这种情况下，作者将在拉取请求描述底部的行中包含评审者的用户名，例如

reviewer: @jpmedley

如果您收到评审请求，并且您被上述方式的另一个评审者覆盖，请不要评审更改。一旦描述中提到的评审者批准了更改，他们将要求 CODEOWNERS 要求的批准。

鼓励评审者阅读以下文章以获取常见任务的帮助

• 关闭的艺术 解释了如何关闭未完成或被拒绝的拉取请求
• 善意和代码评审：改进我们提供反馈的方式 提供了提供反馈的有用提示
• 代码评审指南（针对评审者） 提供了良好反馈和不良反馈的示例