拉取请求提交和审阅

提交更改

价值观和参与

我们希望 MDN Web 文档成为一个热情友好的社区，一个我们都能引以为傲的社区。所有参与者都必须遵守我们的社区参与准则，该准则源自 Mozilla 的社区参与准则。在打开拉取请求、撰写评审评论、与拉取请求作者或其他社区成员互动时，请保持礼貌和建设性。如果您或其他人经历了潜在的非法行为，或让您感到不安全、不受欢迎或不舒服，我们鼓励您举报。

开始之前

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

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

• 如果您希望为项目贡献，您可以在任何MDN GitHub 仓库（例如，mdn/content 问题）的“Issues”下和我们的公共 GitHub 项目面板中找到任务。请确保问题未分配给任何人，并且没有人已经为该任务打开拉取请求。标有 good first issue 的问题是一个很好的开始。

• 如果您在 MDN 上发现了问题，您应该首先打开一个问题。在您开始工作之前，问题需要维护者的回复，这样您就知道拉取请求解决的问题是有效的，并且您的拉取请求将被接受。有关问题的更多信息可以在我们的GitHub 问题的社区页面上找到。

• 如果您想建议新内容或新功能，请通过“新内容或功能建议”GitHub 问题模板提交提案。

如果您不确定从何开始，请在 Discord 服务器上联系我们寻求反馈。

打开拉取请求

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

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

打开拉取请求后

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

拉取请求评审流程

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

如果您想评审拉取请求但未被列为评审者，您可以将自己添加为评审者。礼貌的做法是先在拉取请求上评论，表明您打算开始评审，与现有评审者进行确认。

评审者和分配者

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

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

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

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

如果任何任务失败或存在合并冲突，请将其告知作者；解决这些问题是他们的责任。您可以将作者设置为分配者，以指示拉取请求在开始评审之前需要他们的关注。请为作者留出寻求帮助的空间，尤其是对项目的新贡献者。

评审拉取请求

对于拉取请求中的更改，内容和文字必须符合MDN 写作风格指南，示例代码必须遵循代码风格指南。

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

• 添加评论：在拉取请求中添加评论，让作者知道您已注意到该拉取请求并将开始评审。这是为了避免不必要地同时开始评审拉情况。
• 限制评审范围：仅限于拉取请求中的更改。打开一个后续问题或拉取请求，以解决拉取请求未涵盖的其他改进。
• 寻求帮助：如果您在评审过程中需要技术协助，请添加 review-help-needed 标签。
• 关闭包含不相关更改的拉取请求：如果它过于复杂或包含多个不相关的更改。在这种情况下，请拉取请求作者分批提交他们的更改。
• 请求负载均衡：如果您的工作量已满且没有时间进行评审。标记 @core-yari-content 团队，询问是否有人可以接替。
• 在“depends on”的拉取请求合并之前，请勿合并。
• 不要合并有失败测试的拉取请求。保持 main 分支稳定，避免对贡献者、维护者和自动化流程造成干扰，这是良好的开源礼仪。不稳定的 main 分支会阻塞所有其他拉取请求，并使其他人难以评审和合并贡献。此外，关注仓库的贡献者会收到大量通知，而由失败测试引起的冗余通知可能会令人沮丧。如果您不确定如何修复失败的测试，请寻求帮助或将拉取请求分配给其他人。

如果一个拉取请求除了小的拼写错误或其他小问题外看起来不错，您可能希望直接修复该问题。只要拉取请求已设置为允许更改，您就可以这样做。建议使用带有建议的评论来修复小问题，因为它们可以批量提交。

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

请求更改

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

Comment

当您的反馈不关键且不需要重新评审时，请使用“评论”选项。简而言之，您相信作者和其他评审者会做出良好的判断。

批准

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

如果遇到困难该怎么办

如果您不理解内容更改或觉得它太大太复杂而无法处理，请不要惊慌！一个好的开始方法是向拉取请求作者询问信息以寻求帮助。

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

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

作者和评审者的周转时间指南

本节详细介绍了作为拉取请求作者响应评审意见的预期周转时间，以及作为评审者评审拉取请求的预期周转时间。

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

外部评审者

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

reviewer: @jpmedley

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

阅读列表

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

• The Art of Closing 解释了如何关闭未完成或被拒绝的拉取请求。
• Kindness and Code Reviews: Improving the Way We Give Feedback 提供了有用的反馈提示。
• Code Review Guidelines for the Reviewer 提供了良好和不良反馈的示例。
• How to do a code review on google.github.io/eng-practices。