贡献文档

在首次贡献之前

在贡献之前，你需要

• 注册一个免费的 GitHub 账号，Symfony 文档托管在该服务上。
• 熟悉 reStructuredText 标记语言，Symfony 文档使用它编写。阅读 这篇文章 以快速了解。

快速在线贡献

如果你正在进行相对较小的更改 - 例如修复错别字或重新措辞 - 最简单的贡献方式是直接在 GitHub 上进行！你可以在阅读 Symfony 文档时进行此操作。

步骤 1. 点击页面顶部的 编辑此页 按钮，你将被重定向到 GitHub

步骤 2. 如果这是你的首次贡献，你必须 fork 仓库。然后，编辑内容，预览你的更改（点击左上角的按钮），然后点击 提交更改... 按钮。在弹窗中，描述你的更改，然后点击 提出更改 按钮。

步骤 3. GitHub 现在将为你的更改创建一个分支和一个 commit，并且它还将显示你的更改预览

如果一切正确，点击 创建拉取请求 按钮。

步骤 4. GitHub 将显示一个新页面，你可以在创建拉取请求之前对其进行最后的修改。对于简单的贡献，你可以安全地忽略这些选项，只需再次点击 创建拉取请求 按钮。

恭喜！ 你刚刚为官方 Symfony 文档创建了一个拉取请求！社区现在将审核你的拉取请求，并（可能）提出调整建议。

如果你的贡献很大，或者你更喜欢在自己的计算机上工作，请继续阅读本指南，以学习向 Symfony 文档发送拉取请求的另一种方法。

你的首次文档贡献

在本节中，你将学习如何首次为 Symfony 文档做出贡献。下一节将解释你在首次贡献之后，将来每次贡献时将遵循的更简短的流程。

假设你想改进安装指南。为了进行更改，请按照以下步骤操作

步骤 1. 前往位于 github.com/symfony/symfony-docs 的官方 Symfony 文档仓库，点击 Fork 按钮，将仓库 fork 到你的个人帐户。这仅在你首次为 Symfony 贡献时需要。

步骤 2. 将 fork 的仓库 克隆 到你的本地机器（此示例使用 projects/symfony-docs/ 目录来存储文档；请根据需要更改此值）

1
2

$ cd projects/
$ git clone [email protected]:YOUR-GITHUB-USERNAME/symfony-docs.git

步骤 3. 执行以下命令，将原始 Symfony 文档仓库添加为 "Git 远程仓库"

1
2

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

如果一切顺利，当列出你的项目的 "远程仓库" 时，你将看到以下内容

1
2
3
4
5

$ git remote -v
origin  [email protected]:YOUR-GITHUB-USERNAME/symfony-docs.git (fetch)
origin  [email protected]:YOUR-GITHUB-USERNAME/symfony-docs.git (push)
upstream  https://github.com/symfony/symfony-docs.git (fetch)
upstream  https://github.com/symfony/symfony-docs.git (push)

执行以下命令，获取上游分支的所有提交

1

$ git fetch upstream

此步骤的目的是允许你同时在官方 Symfony 仓库和你的 fork 上工作。你稍后将看到它的实际应用。

步骤 4. 为你的更改创建一个专用的 新分支。为新分支使用简短且易于记忆的名称（如果你正在修复报告的问题，请使用 fix_XXX 作为分支名称，其中 XXX 是问题的编号）

1

$ git checkout -b improve_install_article upstream/5.4

在本示例中，分支的名称为 improve_install_article，而 upstream/5.4 值告诉 Git 基于 upstream 远程仓库（即原始 Symfony 文档仓库）的 5.4 分支创建此分支。

修复应始终基于包含错误的最旧维护分支。目前这是 5.4 分支。如果你要记录新功能，请切换到包含该功能的第一个 Symfony 版本，例如 upstream/6.2。

步骤 5. 现在在文档中进行更改。添加、调整、重写甚至删除任何内容，并尽最大努力遵守 文档标准。然后 提交 你的更改！

1
2
3

# if the modified content existed before
$ git add setup.rst
$ git commit setup.rst

步骤 6. 将更改 推送 到你的 fork 仓库

1

$ git push origin improve_install_article

origin 值是对应于你的 fork 仓库的 Git 远程仓库的名称，而 improve_install_article 是你之前创建的分支的名称。

步骤 7. 现在一切都已准备就绪，可以发起一个 拉取请求。前往你的 fork 仓库 https://github.com/YOUR-GITHUB-USERNAME/symfony-docs，然后点击位于侧边栏中的 拉取请求 链接。

然后，点击大的 新拉取请求 按钮。由于 GitHub 无法猜测你想要提出的确切更改，请选择应应用更改的适当分支

在本示例中，基础 fork 应该是 symfony/symfony-docs，而 基础 分支应该是 5.4，这是你选择作为更改基础的分支。头部 fork 应该是你的 symfony-docs fork 副本，而 比较 分支应该是 improve_install_article，这是你创建并进行更改的分支的名称。

步骤 8. 最后一步是准备拉取请求的 描述。一个简短的短语或段落描述建议的更改就足以确保你的贡献可以被审核。

步骤 9. 既然你已成功提交了你的首次 Symfony 文档贡献，去庆祝一下吧！文档管理员将在短时间内仔细审核你的工作，并告知你任何需要的更改。

如果你被要求添加或修改某些内容，请不要创建新的拉取请求。相反，请确保你在正确的分支上，进行更改并 推送 新的更改

1
2
3
4
5
6

$ cd projects/symfony-docs/
$ git checkout improve_install_article

# ... do your changes

$ git push

很少见，但你可能会被要求 rebase 你的拉取请求以定位另一个 Symfony 分支。阅读 关于 rebase 拉取请求的指南。

步骤 10. 在你的拉取请求最终被接受并合并到 Symfony 文档中之后，你将被列入 Symfony 文档贡献者 列表。此外，如果你碰巧拥有 SymfonyConnect 个人资料，你将获得一个很酷的 Symfony 文档徽章。

你的后续文档贡献

看看你！你已经为 Symfony 文档做出了你的首次贡献！有人开个派对吧！你的首次贡献花费了一些额外的时间，因为你必须学习一些标准并设置你的计算机。但从现在开始，你的贡献将更容易完成。

这是一份 步骤清单，它将指导你完成你的下一次 Symfony 文档贡献

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# create a new branch based on the oldest maintained version
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout -b my_changes upstream/5.4

# ... do your changes

# (optional) add your changes if this is a new content
$ git add xxx.rst

# commit your changes and push them to your fork
$ git commit xxx.rst
$ git push origin my_changes

# ... go to GitHub and create the Pull Request

# (optional) make the changes requested by reviewers and commit them
$ git commit xxx.rst
$ git push

在完成你的后续贡献之后，还要关注你在 Symfony 文档贡献者 列表中的排名提升。你猜对了：在所有这些辛勤工作之后，现在是 再次庆祝的时候了！

检查你的更改

Symfony 仓库会自动检查每个拉取请求，以查找常见错误、不当词语、代码块中的语法问题等。

或者，你也可以在本地机器上构建文档，以调试问题或离线阅读文档。为此，请按照 symfony-docs 仓库的 README 文件中包含的说明进行操作。

常见问题