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

本文以使用PyCharm进行飞桨中文文档修复为例,详细介绍了如何给飞桨提交PR(Pull Request)。
一文读懂如何使用PyCharm为飞桨提PR_第1张图片

背景介绍

关于飞桨框架

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

为什么要进行Pull Request

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

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

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

关于PaddlePaddle/docs

PaddlePaddle/docs存放了飞桨中文文档,我们平时查看的API文档就存放在这个仓库下,如果你在浏览这个文档时发现有的API解释不清楚、示例不明晰、找不到对应的API说明,都可以在PaddlePaddle/docs中提交issue,或者提交PR进行修改。
一文读懂如何使用PyCharm为飞桨提PR_第2张图片

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

关于PaddlePaddle/Paddle

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

前置准备

GitHub

首先,需要一个GitHub账号,在GitHub直接注册即可。之后,进入到PaddlePaddle/docs点击右上角的fork,创建一个属于自己的PaddlePaddle/docs副本。
一文读懂如何使用PyCharm为飞桨提PR_第3张图片

此时,你就拥有了一个对应的下载地址,比如你的昵称是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

一文读懂如何使用PyCharm为飞桨提PR_第4张图片

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

修改分支

进入项目后,通过左下角的Git选框进入分支序列,并且右键当前分支,新建一个分支。
一文读懂如何使用PyCharm为飞桨提PR_第5张图片

安装pre-commit

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

在PyCharm里想要安装pre-commit可以通过控制台,也可以通过“文件-项目-解释器”进行安装,只要保证版本号是2.17.0即可。
一文读懂如何使用PyCharm为飞桨提PR_第6张图片

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

修改文档

以飞桨中绝对值函数API paddle.abs为例,打开对应.rst文件,删除其中一些空行。
一文读懂如何使用PyCharm为飞桨提PR_第7张图片

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

提交

在左侧的提交条目,选择想要提交的文件,插入一个说明,并点击提交并推送。PyCharm会自动调用pre-commit进行格式检查。
一文读懂如何使用PyCharm为飞桨提PR_第8张图片

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

进行PR

回到GitHub网页,在你的docs目录下可以看到Compare&pull request的提示。当然,你也可以通过点击pull request→New pull request进行提交PR。
一文读懂如何使用PyCharm为飞桨提PR_第9张图片
之后在弹出页面中填写PR的目的、内容,形式类似于写邮件。注意在标题处明确表达自己的意图,并在正文中进行详尽描述。
一文读懂如何使用PyCharm为飞桨提PR_第10张图片

最后,点击Create pull request即可。之后,你可以通过PaddlePaddle/docs→Pull requests看到你和其他人的PR,并且审阅大家的工作内容,留下一些友善的建议/评论。以刚刚创建的PR为例,创建后的界面如下:
一文读懂如何使用PyCharm为飞桨提PR_第11张图片

后续事项

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

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

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

如果你对提PR仍有问题,欢迎在评论区留言或扫描下方图片二维码沟通咨询~
一文读懂如何使用PyCharm为飞桨提PR_第12张图片

关注【飞桨PaddlePaddle】公众号,获取更多技术内容~

你可能感兴趣的:(AI,框架,pycharm,paddlepaddle,python)