如何给Paddle库进行PR提交[以Paddle/docs和Pycharm为例]

本文以使用Pycharm进行Paddle中文文档修复为例，尽可能详实地介绍了如何给Paddle提交Pr（pull request）。

本教程可能会有一些疏漏，如果有任何问题，请在本项目下评论。
你的评论有助于这个教程更加充实！谢谢~

背景介绍

关于Paddle

Paddle是一个开源深度学习框架，源代码公开在Github上的PaddlePaddle中。可以在上述链接找到大部分官方库，包括Paddle框架、PaddleSeg分割套件、docs中文文档等。

为什么要进行pull request

Paddle并非是一个仅由百度的内部研发工程师进行维护的库，它支持也欢迎任何人进行代码贡献。

如果你希望在Paddle中增加一个功能或者修复一个bug，你可以：

1. 提交issue，也就是告知他人你的需求；
2. 自己攥写代码，并且进行pull request（pr），当仓库管理员审核你的代码后（可以理解为批准你的修改后），你的代码将被合并到Paddle的代码中。其他程序员使用Paddle时就会运行到你写的代码啦。

除此之外，Paddle也举办了非常丰富的活动，如飞桨黑客马拉松、飞桨快乐开源活动等，参加这些活动的一个小门槛就是能够进行Pr。

关于PaddlePaddle/docs

PaddlePaddle/docs存放了飞桨中文文档，我们平时查看的API文档就存放在这个仓库下，如果你在浏览这个文档的时候发现有的API解释的不是很清楚，或者示例不够明晰，或者找不到对应的API说明，都可以在Paddle/docs中提交issue，或者提交pr进行修改。

此外，相对于Paddle主库，docs库没有大量的格式审查（格式审查意味着，当你提交失败时，你可能需要反复修改你的代码以契合格式），提交难度较低，非常适合大家进行pr提交练习~

关于PaddlePaddle/Paddle

PaddlePaddle/Paddle是Paddle主框架的代码仓库，你可以理解为，PaddlePaddle/docs是中文文档仓库，PaddlePaddle/Paddle是源代码仓库。

需要特别注意的是，中文文档拥有一个专门的仓库PaddlePaddle/docs，但英文文档以注释的形式存在于Paddle的源代码中。通常中英文文档应当保持一致。

前置准备

Github

首先，需要一个Github账号，在Github直接注册即可。

之后，进入到Paddle/docs点击右上角的fork，创建一个属于自己的Paddle/docs副本。

这个时候，你就拥有了一个对应的下载地址，比如你的昵称是Example，你的Paddle/docs下载链接就是https://github.com/Example/docs.git

Pycharm

本项目使用Pycharm，你可以使用其他任何本地编辑器代替。

从Pycharm下载地址下载社区版安装即可。

在Pycharm上获取Paddle/docs并修改提交

获取Paddle/docs

打开Pycharm点击从VCS获取，输入对应的URLhttps://github.com/Example/docs.git即可。

如果拉取项目失败了，请换个时间试试，国内成功全靠概率，大约有超过40%的概率能获取成功。

成功拉取后，如果提示说是否信任项目，直接选择信任即可。

修改分支

进入项目后，通过左下角的Git选框进入Branch序列，并且右键当前分支，新建一个分支。

安装pre-commit

pre-commit是一个格式预检查工具，能够在你进行提交的时候进行格式审查，对于有些Github仓库来说不太需要这个工具，但在Paddle库提交的时候有这么一个工具能够帮你在提交之前查出代码里的问题。

在Pycharm里想要安装pre-commit可以通过控制台，也可以通过“文件-项目-解释器”进行安装，只要保证版本号是2.17.0即可。

之后，在控制台执行pre-commit install即可。如果你的控制台不能执行，请通过“文件-项目-解释器”修改你的Python环境为venv。

修改文档

以绝对值函数paddle.abs为例，打开对应.rst文件，删除其中一些空行。

修改后的文档可以通过左侧提交进行审阅。

提交

还是在左侧的提交条目，选择想要提交的文件，插入一个说明，并点击提交并推送即可。Pycharm会自动调用pre-commit进行格式检查。

提交成功后，就可以看到左下角提示你提交成功。

进行PR

回到github网页，在你的docs目录下就可以看到Compare & pull request的提示，当然，你也可以通过点击pull request - new pull request进行提交pr。

之后在弹出页面中填写PR的目的，内容即可，类似于写一封邮件，在标题处明确表明自己的意图，在正文中进行详尽描述。

最后，点开Create Pull Request即可。之后，你可以通过Paddle/docs - Pull Request看到你和其他人的pr，并且审阅大家的工作内容，留下一些友善的建议/评论。以刚刚创建的Pr为例，创建后的界面如下

后续事项

如果你进行的改动非常完美，之后会收到一封邮件，表明你的PR已经被合入；如果你的改动仍需调整，你会在上述页面中收到审阅人的建议/意见，你可以对你的PR进行解释，以拒绝这些建议/意见，也可以根据意见进行修改，但无论如何请进行回复，不然这个PR将永远无法被合入（因为合入的基础是这个PR得到了审阅人的认可）。

本教程可能会有一些疏漏，如果有任何问题，请在本项目下评论。

你的评论有助于这个教程更加充实！谢谢~

请点击此处查看本环境基本用法.

Please click here for more detailed instructions.

此文章为搬运
原项目链接