提出更改

安装软件栈

在开始使用 Symfony 之前，请使用以下软件设置友好的环境

• Git；
• PHP 版本 8.2 或更高版本。

配置 Git

使用您的真实姓名和可用的电子邮件地址设置您的用户信息

1
2

$ git config --global user.name "Your Name"
$ git config --global user.email [email protected]

1

$ git config core.autocrlf

1

$ git config --global core.autocrlf input

获取 Symfony 源代码

获取 Symfony 源代码

• 创建 GitHub 帐户并登录；
• Fork Symfony 存储库（单击 “Fork” 按钮）；
• 取消选中 “仅复制 X.Y 分支”；
• “fork” 操作完成后，在本地克隆您的 fork（这将创建一个 symfony 目录）

1

$ git clone [email protected]:USERNAME/symfony.git

• 将上游存储库添加为远程仓库

1
2

$ cd symfony
$ git remote add upstream https://github.com/symfony/symfony.git

检查当前测试是否通过

现在 Symfony 已安装，请检查您的环境中所有单元测试是否通过，如专门的文档中所述。

许可证

在开始之前，您应该意识到您要提交的所有代码都必须根据 *MIT 许可证* 发布。

选择正确的分支

在处理 PR 之前，您必须确定需要在哪个分支上工作

• 如果您正在修复现有功能的错误，或者想进行属于补丁版本中可接受的更改列表的更改，请选择最旧的相关维护分支（您可以在 Symfony 发布页面上找到它们）。 例如，如果您发现 v5.1.10 中引入的错误，则需要在 5.4 上工作。

• 7.2，如果您要添加新功能。

  唯一的例外是每两年发布一个新的 Symfony 主要版本（5.0、6.0 等）。 由于这些版本的特殊开发过程，您需要为功能使用之前的次要版本（例如，使用 5.4 而不是 6.0，使用 6.4 而不是 7.0 等）。

在稳定阶段，开发分支处于功能冻结状态。 请帮助社区为新版本发布做准备。 如果您想提交新的功能 pull request，则应以下一个版本为目标。 例如，如果 6.3 达到功能冻结状态，则新功能应以 6.4 为目标。 如果 6.4 分支尚不存在，则以 6.3 为目标，并在分支创建后 rebase 您的 pull request。

创建主题分支

每次您想处理错误或增强功能的 PR 时，都创建一个主题分支

1

$ git checkout -b BRANCH_NAME 6.1

或者，如果您想为 5.4 分支提供错误修复，请首先在本地跟踪远程 5.4 分支

1

$ git checkout --track origin/5.4

然后从 5.4 分支创建一个新分支来处理错误修复

1

$ git checkout -b BRANCH_NAME 5.4

上面的 checkout 命令会自动将代码切换到新创建的分支（使用 git branch 检查您正在处理的分支）。

在现有项目中使用您的分支

如果您想在使用 symfony/symfony 或 Symfony 组件的现有项目中测试您的代码，则可以使用您之前克隆的 Git 存储库中提供的 link 实用程序。 此工具会扫描您项目的 vendor/ 目录，查找它使用的 Symfony 包，并将它们替换为指向 Git 存储库中包的符号链接。

1

$ php link /path/to/your/project

在运行 link 命令之前，请确保通过在其内部运行 composer install 来安装要调试的项目的依赖项。

处理您的 Pull Request

尽可能多地处理代码并提交，但请记住以下几点

• 阅读有关 Symfony 约定并遵循编码标准（使用 git diff --check 检查尾随空格 -- 另请阅读下面的提示）；
• 添加单元测试以证明错误已修复或新功能确实有效；
• 尽力不破坏向后兼容性（如果必须这样做，请尝试提供兼容层以支持旧方法）-- 破坏向后兼容性的 PR 合并的可能性较小；
• 进行原子且逻辑上分离的提交（利用 git rebase 的强大功能来获得干净且逻辑的历史记录）；
• 永远不要修复一些现有代码中的编码标准，因为它会使代码审查更加困难；

• 编写良好的提交消息：以简短的主题行（第一行）开头，后跟一个空行和更详细的描述。

  主题行应以您正在处理的组件、Bridge 或 Bundle 的方括号开头（[DependencyInjection]，[FrameworkBundle]，...）。

  然后，将句子大写，不要以句点结尾，并使用祈使动词开头。

  这是一个主题行的完整示例：[MagicBundle] 添加 `MagicConfig`，允许配置事物。

准备您的 Pull Request 以供提交

当您的 PR 不是关于错误修复时（例如，当您添加新功能或更改现有功能时），它还必须包括以下内容

• 相关 CHANGELOG 文件中对更改的说明（相关时必须使用 [BC BREAK] 或 [DEPRECATION] 前缀）；
• 如果更改破坏了向后兼容性，或者如果您弃用了最终会破坏向后兼容性的内容，则在相关的 UPGRADE 文件中解释如何升级现有应用程序。

Rebase 您的 Pull Request

在提交 PR 之前，更新您的分支（如果您需要一段时间才能完成更改，则需要这样做）

1
2
3
4
5

$ git checkout 6.x
$ git fetch upstream
$ git merge upstream/6.x
$ git checkout BRANCH_NAME
$ git rebase 6.x

在执行 rebase 命令时，您可能需要修复合并冲突。 git status 将显示*未合并*的文件。 解决所有冲突，然后继续 rebase

1
2

$ git add ... # add resolved files
$ git rebase --continue

检查所有测试是否仍然通过，并将您的分支远程推送

1

$ git push --force origin BRANCH_NAME

创建 Pull Request

您现在可以在 symfony/symfony GitHub 存储库上创建 pull request。

为了方便核心团队的工作，请始终在您的 pull request 消息中包含修改后的组件，如下所示

1
2

[Yaml] fixed something
[Form] [Validator] [FrameworkBundle] added something

默认的 pull request 描述包含一个表格，您必须在其中填写适当的答案。 这确保了可以审查贡献而无需不必要的反馈循环，并且您的贡献可以尽快包含到 Symfony 中。

某些问题的答案会触发更多要求

• 如果您对 “错误修复？” 回答是，请检查该错误是否已在 Symfony issues 中列出，并在 “Issues” 中引用它/它们；
• 如果您对 “新功能？” 回答是，您必须向文档提交 pull request，并在 “Doc PR” 部分下引用它；
• 如果您对 “BC 破坏？” 回答是，则 PR 必须包含对相关的 CHANGELOG 和 UPGRADE 文件的更新；
• 如果您对 “弃用？” 回答是，则 PR 必须包含对相关的 CHANGELOG 和 UPGRADE 文件的更新；
• 如果您对 “测试通过” 回答否，则必须在 todo 列表中添加一个条目，其中包含修复测试必须执行的操作；
• 如果 “许可证” 不是 MIT，请不要提交 pull request，因为它无论如何都不会被接受。

如果未满足之前的某些要求，请创建一个 todo 列表并添加相关项

1
2
3

- [ ] fix the tests as they have not been updated yet
- [ ] submit changes to the documentation
- [ ] document the BC breaks

如果代码尚未完成，因为您没有时间完成它，或者因为您想要对您的工作进行早期反馈，请在 todo 列表中添加一个项目

1
2

- [ ] finish the code
- [ ] gather feedback for my changes

只要您的 todo 列表中有项目，请在 pull request 标题前加上 “[WIP]”。

在 pull request 描述中，尽可能详细地说明您的更改（请随时提供代码示例来说明您的观点）。 如果您的 pull request 是关于添加新功能或修改现有功能，请解释更改的基本原理。 pull request 描述有助于代码审查，并且在合并代码时充当参考（pull request 描述及其所有相关评论是合并提交消息的一部分）。

除了这个“代码”拉取请求之外，您还必须向 文档仓库 发送拉取请求，以便在适当的时候更新文档。

自动化反馈

有许多自动化脚本会提供关于拉取请求的反馈。

1

$ psalm.phar src/Symfony/Component/Workflow

自动化测试

提交拉取请求时，将运行一系列自动化测试。这些测试在不同的条件下测试代码，以确保没有重要的东西被破坏。测试失败可能与您的更改无关。如果您认为情况是这样，您可以检查目标分支是否具有相同的错误，并在您的 PR 上留下评论。

否则，测试失败可能是由您的更改引起的。以下测试场景在每次更改时运行：

PHPUnit / 测试

此作业在 Ubuntu 上使用多个 PHP 版本（每个版本都在其自己的作业中）运行。这些作业运行测试套件，就像您在本地所做的那样。

这些作业中的失败通常表示代码中存在错误。

PHPUnit / 测试 (high-deps)

此作业通过从每个软件包内部调用 composer update 和 phpunit，单独检查 src/ 中的每个软件包（bridge、bundle 或 component）。

此作业中的失败通常表示在失败软件包的 composer.json 中缺少软件包（例如 src/Symfony/Bundle/FrameworkBundle/composer.json）。

此作业还使用“翻转”测试（由软件包名称中的 ^ 后缀表示）运行相关软件包。这些测试检出之前的 major 版本（例如，对于 6.3 上的拉取请求，为 5.4），并使用您的分支作为依赖项运行测试。

这些翻转测试中的失败表示您的更改中存在向后兼容性中断。

PHPUnit / 测试 (low-deps)

此作业也单独检查每个软件包，但随后在使用测试之前使用 composer update --prefer-lowest。

此作业中的失败通常表示在失败软件包的 composer.json 中版本范围错误或缺少软件包。

continuous-integration/appveyor/pr

此作业在 Windows 上使用 x86 架构和最低支持的 PHP 版本运行。所有测试首先在没有额外 PHP 扩展的情况下运行。然后，所有跳过的测试都使用所有必需的 PHP 扩展运行。

此作业中的失败通常表示您的更改不支持 Windows、x86 或具有最少扩展的 PHP。

集成 / 测试

集成测试需要其他服务（例如 Redis 或 RabbitMQ）才能运行。此作业仅运行 integration PHPUnit 组中的测试。

此作业中的失败表示与这些服务的通信中存在错误。

PHPUnit / 测试 (experimental)

此作业始终通过（即使测试失败），并且核心团队使用它来为即将到来的 PHP 版本做准备。

重新修改您的 Pull Request

根据拉取请求上的反馈，您可能需要修改您的 PR。在重新提交 PR 之前，使用 upstream/6.x 或 upstream/5.4 进行变基，不要合并；并强制推送到 origin

1
2

$ git rebase -f upstream/6.x
$ git push --force origin BRANCH_NAME

版主之前要求您“压缩”您的提交。这意味着您将把许多提交转换为一个提交。今天已不再需要这样做，因为 Symfony 项目使用专有工具，该工具会在合并之前自动压缩所有提交。