一文读懂如何使用PyCharm为飞桨提PR

news2024/11/18 19:43:25

本文以使用PyCharm进行飞桨中文文档修复为例，详细介绍了如何给飞桨提交PR（Pull Request）。
在这里插入图片描述

背景介绍

关于飞桨框架

飞桨框架是一个开源深度学习框架，源代码公开在GitHub上的PaddlePaddle中。该目录下包括飞桨核心框架代码库Paddle、飞桨文档库docs等。

为什么要进行Pull Request

飞桨并非是一个仅由百度研发工程师进行维护的库，它支持也欢迎任何人进行代码贡献。如果你希望在飞桨中增加一个功能或者修复一个bug，你可以：

提交issue，也就是告知他人你的需求或上报bug；
自己攥写代码，并且进行PullRequest（PR），当仓库管理员审核你的代码后（可以理解为认可你的修改后），该代码将被合并到飞桨的代码中，其他程序员使用飞桨时就会运行到你写的代码啦。

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

关于PaddlePaddle/docs

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

此外，docs库没有大量的CI流水线检查，提交难度较低，非常适合大家进行PR提交练习~

关于PaddlePaddle/Paddle

PaddlePaddle/Paddle是飞桨框架的代码仓库，你可以理解为，PaddlePaddle/docs是中文文档仓库，PaddlePaddle/Paddle是源代码仓库。
中文API文档在PaddlePaddle/docs中管理，英文文档以注释的形式存在于飞桨的源代码中。通常中英文文档应当保持一致。

前置准备

GitHub

首先，需要一个GitHub账号，在GitHub直接注册即可。之后，进入到PaddlePaddle/docs点击右上角的fork，创建一个属于自己的PaddlePaddle/docs副本。
在这里插入图片描述

此时，你就拥有了一个对应的下载地址，比如你的昵称是USERNAME；你的PaddlePaddle/docs下载链接：
https://github.com/USERNAME/docs.git

PyCharm

本项目使用PyCharm进行PR教学，你可以使用其他任何本地编辑器代替。从PyCharm官网下载社区版安装即可。

在PyCharm上获取PaddlePaddle/docs并修改提交

获取PaddlePaddle/docs

打开PyCharm点击从VCS获取，输入对应的URL即可。链接：

https://github.com/USERNAME/docs.git

在这里插入图片描述

如果拉取项目失败，建议挂代理后再次尝试，如果不方便设置代理，你可以更换时间再次尝试，个人经验来看大约有超过40%的概率能获取成功。成功拉取后，如提示是否信任项目，直接选择信任即可。

修改分支

进入项目后，通过左下角的Git选框进入分支序列，并且右键当前分支，新建一个分支。
在这里插入图片描述

安装pre-commit

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

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

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

修改文档

以飞桨中绝对值函数API paddle.abs为例，打开对应.rst文件，删除其中一些空行。
在这里插入图片描述

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

提交

在左侧的提交条目，选择想要提交的文件，插入一个说明，并点击提交并推送。PyCharm会自动调用pre-commit进行格式检查。
在这里插入图片描述

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

进行PR

回到GitHub网页，在你的docs目录下可以看到Compare&pull request的提示。当然，你也可以通过点击pull request→New pull request进行提交PR。
在这里插入图片描述
之后在弹出页面中填写PR的目的、内容，形式类似于写邮件。注意在标题处明确表达自己的意图，并在正文中进行详尽描述。

最后，点击Create pull request即可。之后，你可以通过PaddlePaddle/docs→Pull requests看到你和其他人的PR，并且审阅大家的工作内容，留下一些友善的建议/评论。以刚刚创建的PR为例，创建后的界面如下：
在这里插入图片描述

后续事项

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

所以，你学会了吗？快速练习上手&检验学习成果的时候到了，快来参加：飞桨快乐开源活动：快来提PR，领取新年礼物啦

为鼓励更多的开发者参与到飞桨社区的开源建设中，帮助社区修复bug或贡献feature，加入开源、共建飞桨。飞桨快乐开源活动暖冬来袭，我们提供了三种类型的贡献任务，并为完成任务的贡献者准备了礼品表示感谢！

如果你对提PR仍有问题，欢迎在评论区留言或扫描下方图片二维码沟通咨询~
在这里插入图片描述