参与贡献文档

在首次贡献之前¶

在开始贡献前，你应该首先了解：

• Symfony文档采用 reStructuredText 标记语言书写。如果你不熟悉这种格式，请阅读 这篇文章 来快速了解它的特征

• Symfony文档托管在 GitHub 上。 你需要一个Github账户来参与贡献文档。

• Symfony文档遵循 Creative Commons BY-SA 3.0 协议 并且你的所有贡献也都将默认跟随此协议。

首次文档贡献¶

在本小节中，你将学习怎样首次参与文档贡献。下一节将介绍每次你参与文档贡献的操作流程。

现在假设你想要改善《Symfony教程》中《安装》这一章节。为了实现更改，跟随如下几步：

第一步 访问Symfony官方文档库地址 github.com/symfony/symfony-docs 并且 fork the repository 到你的个人账号。只需进行一次这样的操作。

第二步 Clone 分支仓库到你的本地 （如下例子使用 projects/symfony-docs/ 目录来存储文档;请修改<YOUR GITHUB USERNAME>）:

$ cd projects/
$ git clone git://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git

第三步 在修改前，切换到 最旧的维护分支 。目前为 2.3 分支：（译者注：此中文文档将一直跟随最新的版本，请忽略此条）

$ cd symfony-docs/
$ git checkout 2.3

如果你是要参与贡献最新特性的文档，请切换到最新的Symfony版本：2.5，2.6，等。

第四步 为你的修改创建一个专用的 新分支。这将极大的简化你的修订与合并工作。可以采用一个简单好记的名字来命名你的新分支：

$ git checkout -b improve_install_chapter

第五步 在文档中做些修改。添加、调整、改写，甚至删除现有的内容，但请确保你遵守了文档标准 Documentation Standards.

第六步 将修改**Push**到forked库的improve_install_chapter分支:

$ git commit book/installation.rst
$ git push origin improve_install_chapter

第七步 现在就可以发起一个 pull request 了。在你的forked库页面 https//github.com/<YOUR GITHUB USERNAME>/symfony-docs，在侧边栏点击 Pull Requests 链接。

然后点击 New pull request 按钮。由于Github不能明确的知道你要提交的修改，所以需要你选择适当分支上的适当修改来进行提交：

在此例中，base repository 应为 symfony/symfony-docs 并且 base branch 应为 2.3 （修改基于此分支之上）。 compare repository 应为forked库，symfony-docs 并且 compare branch 应为 improve_install_chapter （你创建并修改后的分支）。

第八步 最后一步是填写pull request的 description 。为了确保你的提交能够被快速评估，请把如下的表格添加在你pull request description的开头：

| Q             | A
| ------------- | ---
| Doc fix?      | [yes|no]
| New docs?     | [yes|no] (PR # on symfony/symfony if applicable)
| Applies to    | [Symfony version numbers this applies to]
| Fixed tickets | [comma separated list of tickets fixed by the PR]

在上面的例子中，表格应为:

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #10575

第九步 至此，你已经成功的提交了你的首次文档贡献，恭喜，文档管理员将尽快评估你的工作，并且会让你知晓任何需要的改动。

如果在提交后你发现需要添加或修改，无需创建一个新的pull request。只需确保你在正确的分支，修改并提交到此分支即可。

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

# ... do your changes

$ git push

第十步 在你的pull request最终被接受并合并到Symfony文档的主分支后，你将会加入到 Symfony Documentation Contributors 名单中。此外，如果你加入 SensioLabsConnect ，你将得到 Symfony Documentation Badge 徽章。

第二次文档贡献¶

首次文档贡献花费了一些时间，因为你需要fork文档库，学习怎样书写文档，创建pull requests等。第二次文档贡献将变得非常简单，但需要注意的是，Symfony的文档库在不断的变化中，你Github账户中的分支于官方版本相比很有可能已经不是最新的了。

为了解决这个问题需要 sync your fork 进行库的同步.只需执行这个指令来告诉git，你账户forked库的上游库（原库）：

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

现在你可以 进行同步 :

$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout 2.3
$ git merge upstream/2.3

这个指令将更新 2.3 分支（你用于创建新修改分支的源分支）。如果你使用的是其他源分支，比如 master，将 2.3 替换成master即可.

接下来你就可以仿照上一节中的流程了：

# create a new branch to store your changes based on the 2.3 branch
$ cd projects/symfony-docs/
$ git checkout 2.3
$ git checkout -b my_changes

# ... do your changes

# submit the changes to your forked repository
$ git add xxx.rst     # (optional) only if this is a new content
$ git commit xxx.rst
$ git push origin my_changes

# go to GitHub and create the Pull Request
#
# Include this table in the description:
# | Q             | A
# | ------------- | ---
# | Doc fix?      | [yes|no]
# | New docs?     | [yes|no] (PR # on symfony/symfony if applicable)
# | Applies to    | [Symfony version numbers this applies to]
# | Fixed tickets | [comma separated list of tickets fixed by the PR]

第二次文档贡献完成，恭喜，你也可以看看你在 Symfony Documentation Contributors 贡献列表中的排名。

下一次文档贡献¶

你已经完成了两次文档贡献，你或许已经发现git在此过程中发挥的神奇作用，这也是为什么你的下一次贡献将更加快速。在这里你可以找到一个完整的文档贡献流程 清单

# sync your fork with the official Symfony repository
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout 2.3
$ git merge upstream/2.3

# create a new branch from the oldest maintained version
$ git checkout 2.3
$ git checkout -b my_changes

# ... do your changes

# add and commit your changes
$ git add xxx.rst     # (optional) only if this is a new content
$ git commit xxx.rst
$ git push origin my_changes

# go to GitHub and create the Pull Request
#
# Include this table in the description:
# | Q             | A
# | ------------- | ---
# | Doc fix?      | [yes|no]
# | New docs?     | [yes|no] (PR # on symfony/symfony if applicable)
# | Applies to    | [Symfony version numbers this applies to]
# | Fixed tickets | [comma separated list of tickets fixed by the PR]

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

在上面这些工作完成后，是的，再次恭喜！

小修改（比如拼写错误）¶

You may find just a typo and want to fix it. Due to GitHub’s functional frontend, it is quite simple to create Pull Requests right in your browser while reading the docs on symfony.com. To do this, just click the edit this page button on the upper right corner. Beforehand, please switch to the right branch as mentioned before. Now you are able to edit the content and describe your changes within the GitHub frontend. When your work is done, click Propose file change to create a commit and, in case it is your first contribution, also your fork. A new branch is created automatically in order to provide a base for your Pull Request. Then fill out the form to create the Pull Request as described above.

常见问题¶