\u200E
一文读懂如何使用PyCharm为飞桨提PR
发布日期:2022-12-09T10:01:20.000+0000 浏览量:1018次
本文以使用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仍有问题,欢迎在 评论区留言 扫描下方图片二维码 沟通咨询~
 
关注【飞桨PaddlePaddle】公众号
获取更多技术内容~