社区评论

为什么审阅很重要

社区审阅对于 Symfony 框架的开发至关重要，因为 pull request 和 bug 报告的数量远远多于 Symfony 核心团队成员的数量，而核心团队成员需要审阅、修复和合并它们。

在 Symfony issue 跟踪器上，你可以找到许多处于 Needs Review 状态的项目

• Bug 报告：Bug 报告需要检查完整性。是否有任何重要信息缺失？Bug 能否被重现？
• Pull Request：Pull request 包含修复 bug 或实现新功能的代码。Pull request 的审阅确保它们被正确实现，被测试用例覆盖，不会引入新的 bug，并保持向后兼容性。

请注意，任何对 Symfony 和 PHP 有基本了解的人都可以审阅 bug 报告和 pull request。你不需要成为专家也能提供帮助。

保持建设性

在你开始之前，请记住你正在查看别人辛勤工作的成果。一个好的审阅评论会感谢贡献者的工作，指出哪些地方做得好，哪些地方应该改进，并提出下一步的建议。

创建 GitHub 账号

Symfony 使用 GitHub 来管理 bug 报告和 pull request。如果你想进行审阅，你需要创建一个 GitHub 账号并登录。

Bug 报告审阅流程

开始审阅的一个好方法是从需要审阅的 bug 报告中选择一个 bug 报告。

审阅的步骤如下：

1. 报告是否完整？

   好的 bug 报告包含一个指向使用 Symfony 骨架创建的项目（“重现项目”）的链接，该项目重现了该 bug。如果它没有，报告至少应包含足够的信息和代码示例来重现该 bug。

2. 重现 Bug

   下载重现项目，并测试 bug 是否可以在你的系统上重现。如果报告者没有提供重现项目，请基于 Symfony 骨架创建一个。

3. 更新 Issue 状态

   最后，在 bug 报告中添加评论。感谢报告者报告 bug。在你的评论中包含 Status: <status> 行，以触发我们的 Carson Bot，它会更新 issue 的状态标签。你可以将状态设置为以下之一：

   需要改进：如果 bug 不包含足够的信息来重现，请解释缺少哪些信息，并将报告移至此状态。

   对我有效：如果 bug 确实包含足够的信息来重现，但在你的系统上可以正常工作，或者如果报告的 bug 是一个功能而不是 bug，请提供简短的解释并将报告移至此状态。

   已审阅：如果你可以重现 bug，请将报告移至此状态。如果你创建了一个重现项目，请在你的评论中包含指向该项目的链接。

1
2
3
4
5

Thank you @weaverryan for creating this bug report! This indeed looks
like a bug. I reproduced the bug in the "kernel-bug" branch of
https://github.com/webmozart/some-project.

Status: Reviewed

Pull Request 审阅流程

审阅 pull request (PR) 的过程与 bug 报告类似。Pull request 的审阅通常需要更长的时间，因为你需要理解已修复或添加的功能，并确定实现是否完整。

进行部分审阅是可以的！如果你进行部分审阅，请评论你完成了多少，并将 PR 留在“Needs Review”状态。

从 需要审阅的 PR 中选择一个 pull request，并按照以下步骤操作：

1. PR 是否完整?

   每个 pull request 都必须包含一个标题，其中包含有关 PR 的一些基本信息。你可以在贡献指南中找到该标题的模板。

2. 基础分支是否正确？

   GitHub 在 pull request 标题下方显示 PR 所基于的分支。该分支是否正确？

   • Bug 应该在包含该 bug 的最旧的、维护的版本中修复。查看 Symfony 的发布时间表以查找最旧的当前支持版本。
   • 新功能应始终添加到当前开发版本中。查看 Symfony 路线图以查找当前开发版本。

3. 重现问题

   阅读 pull request 旨在修复的 issue。在用 Symfony 骨架创建的新项目上重现问题，并尝试理解它为什么存在。如果链接的 issue 已经包含这样的项目，请安装并在你的系统上运行它。

4. 审阅代码

   阅读 pull request 的代码，并根据一些通用标准进行检查：

   • 代码是否解决了 PR 旨在修复/实现的 issue？
   • PR 是否保持在范围内，仅解决该 issue？
   • PR 是否包含自动化测试？这些测试是否涵盖了所有相关的边缘情况？
   • PR 是否包含足够的注释来理解其代码？
   • 代码是否破坏了向后兼容性？如果是，PR 标题是否说明了这一点？
   • PR 是否包含弃用？如果是，PR 标题是否说明了这一点？代码是否包含所有已弃用功能的 trigger_deprecation() 语句？
   • 所有弃用和向后兼容性破坏是否都记录在最新的 UPGRADE-X.X.md 文件中？这些解释是否包含带有清晰升级说明的“之前”/“之后”示例？

   注意

   最终，其中一些方面将自动检查。

5. 测试代码

   从步骤 3 中获取你的项目，并测试 PR 是否正常工作。通过运行以下 Git 命令，将 vendor 目录中的 Symfony 项目替换为 PR 中的代码。为 <ID> 占位符插入 PR ID（PR 标题中 # 后的数字）：

   1
   2
   3

   $ cd vendor/symfony/symfony
   $ git fetch origin pull/<ID>/head:pr<ID>
   $ git checkout pr<ID>

   例如

   1
   2

   $ git fetch origin pull/15723/head:pr15723
   $ git checkout pr15723

   现在你可以根据 PR 中的代码测试项目。

6. 更新 PR 状态

   最后，在 PR 中添加评论。感谢贡献者为 PR 所做的工作。在你的评论中包含 Status: <status> 行，以触发我们的 Carson Bot，它会更新 issue 的状态标签。你可以将状态设置为以下之一：

   需要改进：如果 PR 尚未准备好合并，请解释你发现的问题，并将其移至此状态。

   已审阅：如果 PR 满足上述所有检查，请将其移至此状态。核心贡献者将很快查看 PR，并决定是否可以合并或需要进一步的工作。

1
2
3
4
5

Thank you @weaverryan for working on this! It seems that your test
cases don't cover the cases when the counter is zero or smaller.
Could you please add some tests for that?

Status: Needs Work