Skip to content

Latest commit

 

History

History
262 lines (176 loc) · 10.4 KB

how_to_contribute.md

File metadata and controls

262 lines (176 loc) · 10.4 KB

PaddleVideo 社区贡献指南


目录

一、如何贡献代码

1.1 PaddleVideo 分支说明

PaddleVideo 未来将维护 2 种分支,分别为:

  • release/x.x.x 系列分支:为稳定的发行版本分支,会适时打 tag 发布版本,适配 Paddle 的 release 版本。当前最新的分支为 release/2.2.0 分支。随着版本迭代, release/x.x.x 系列分支会越来越多,默认维护最新版本的 release 分支,其他的分支不再维护。
  • develop 分支:为开发分支,也是默认分支,适配 Paddle 的 develop 版本,主要用于开发新功能。如果有同学需要进行二次开发,请选择 develop 分支。为了保证 develop 分支能在需要的时候拉出 release/x.x.x 分支, develop 分支的代码只能使用 Paddle 最新 release 分支中有效的 api 。也就是说,如果 Paddle develop 分支中开发了新的 api,但尚未出现在 release 分支代码中,那么请不要在 PaddleVideo 中使用。除此之外,对于不涉及 api 的性能优化、参数调整、策略更新等,都可以正常进行开发。

PaddleVideo 的历史分支,未来将不再维护。考虑到一些同学可能仍在使用,这些分支还会继续保留:

  • application 分支:这个分支主要存放应用案例相关代码,目前包括VideoTag和FootballAction,后续会将此分支代码迁移至develop分支,并随 release/x.x.x 发版。

PaddleVideo 欢迎大家向 repo 中积极贡献代码,下面给出一些贡献代码的基本流程。

1.2 PaddleVideo 代码提交流程与规范

1.2.1 fork 和 clone 代码

  • 跳转到 PaddleVideo GitHub首页 ,然后单击 Fork 按钮,生成自己目录下的仓库,比如 https://github.com/USERNAME/PaddleVideo
  • 将远程仓库 clone 到本地
# 拉取develop分支的代码
git clone https://github.com/USERNAME/PaddleVideo.git
cd PaddleVideo

clone 的地址可以从下面获取

1.2.2 和远程仓库建立连接

首先通过 git remote -v 查看当前远程仓库的信息。

origin    https://github.com/USERNAME/PaddleVideo.git (fetch)
origin    https://github.com/USERNAME/PaddleVideo.git (push)

上面的信息只包含了 clone 的远程仓库的信息,也就是自己用户名下的 PaddleVideo ,接下来我们创建一个原始 PaddleVideo 仓库的远程主机,命名为 upstream 。

git remote add upstream https://github.com/PaddlePaddle/PaddleVideo.git

使用 git remote -v 查看当前远程仓库的信息,输出如下,发现包括了 origin 和 upstream 2 个远程仓库。

origin    https://github.com/USERNAME/PaddleVideo.git (fetch)
origin    https://github.com/USERNAME/PaddleVideo.git (push)
upstream    https://github.com/PaddlePaddle/PaddleVideo.git (fetch)
upstream    https://github.com/PaddlePaddle/PaddleVideo.git (push)

这主要是为了后续在提交 pull request (PR) 时,始终保持本地仓库最新。

1.2.3 创建本地分支

可以基于当前分支创建新的本地分支,命令如下。

git checkout -b new_branch

也可以基于远程或者上游的分支创建新的分支,命令如下。

# 基于用户远程仓库(origin)的develop创建new_branch分支
git checkout -b new_branch origin/develop
# 基于上游远程仓库(upstream)的develop创建new_branch分支
# 如果需要从upstream创建新的分支,需要首先使用git fetch upstream获取上游代码
git checkout -b new_branch upstream/develop

最终会显示切换到新的分支,输出信息如下

Branch new_branch set up to track remote branch develop from upstream.
Switched to a new branch 'new_branch'

1.2.4 使用 pre-commit 勾子

Paddle 开发人员使用 pre-commit 工具来管理 Git 预提交钩子。 它可以帮助我们格式化源代码(C++,Python),在提交(commit)前自动检查一些基本事宜(如每个文件只有一个 EOL,Git 中不要添加大文件等)。

pre-commit 测试是 Travis-CI 中单元测试的一部分,不满足钩子的 PR 不能被提交到 PaddleVideo ,首先安装并在当前目录运行它:

pip install pre-commit
pre-commit install
  • 注意
  1. Paddle 使用 clang-format 来调整 C/C++ 源代码格式,请确保 clang-format 版本在 3.8 以上。
  2. 通过 pip install pre-commitconda install -c conda-forge pre-commit 安装的 yapf 稍有不同的,PaddleVideo 开发人员使用的是 pip install pre-commit

1.2.5 修改与提交代码

可以通过 git status 查看改动的文件。 对 PaddleVideo 的 README.md 做了一些修改,希望提交上去。则可以通过以下步骤

git add README.md
pre-commit

重复上述步骤,直到 pre-comit 格式检查不报错。如下所示。

使用下面的命令完成提交。

git commit -m "your commit info"

1.2.6 保持本地仓库最新

获取 upstream 的最新代码并更新当前分支。这里的 upstream 来自于 1.2 节的和远程仓库建立连接部分。

git fetch upstream
# 如果是希望提交到其他分支,则需要从upstream的其他分支pull代码,这里是develop
git pull upstream develop

1.2.7 push到远程仓库

git push origin new_branch

1.2.8 提交Pull Request

点击 new pull request,选择本地分支和目标分支,如下图所示。在 PR 的描述说明中,填写该 PR 所完成的功能。接下来等待 review ,如果有需要修改的地方,参照上述步骤更新 origin 中的对应分支即可。

1.2.9 签署 CLA 协议和通过单元测试

  • 签署 CLA 在首次向 PaddlePaddle 提交 Pull Request 时,您需要您签署一次 CLA (Contributor License Agreement) 协议,以保证您的代码可以被合入,具体签署方式如下:
  1. 请您查看 PR 中的 Check 部分,找到 license/cla ,并点击右侧 detail ,进入 CLA 网站
  2. 点击 CLA 网站中的 Sign in with GitHub to agree , 点击完成后将会跳转回您的 Pull Request 页面

1.2.10 删除分支

  • 删除远程分支

在 PR 被 merge 进主仓库后,我们可以在 PR 的页面删除远程仓库的分支。

也可以使用 git push origin :分支名 删除远程分支,如:

git push origin :new_branch
  • 删除本地分支
# 切换到develop分支,否则无法删除当前分支
git checkout develop

# 删除new_branch分支
git branch -D new_branch

1.2.11 提交代码的一些约定

为了使官方维护人员在评审代码时更好地专注于代码本身,请您每次提交代码时,遵守以下约定:

1)请保证 Travis-CI 中单元测试能顺利通过。如果没过,说明提交的代码存在问题,官方维护人员一般不做评审。

2)提交 Pull Request前:

请注意 commit 的数量。

原因:如果仅仅修改一个文件但提交了十几个 commit ,每个 commit 只做了少量的修改,这会给评审人带来很大困扰。评审人需要逐一查看每个 commit 才能知道做了哪些修改,且不排除 commit 之间的修改存在相互覆盖的情况。

建议:每次提交时,保持尽量少的 commit ,可以通过 git commit --amend 补充上次的 commit 。对已经 Push 到远程仓库的多个 commit ,可以参考 squash commits after push

请注意每个 commit 的名称:应能反映当前 commit 的内容,不能太随意。

3)如果解决了某个 Issue 的问题,请在该 Pull Request 的第一个评论框中加上: fix #issue_number ,这样当该 Pull Request 被合并后,会自动关闭对应的 Issue 。关键词包括: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved ,请选择合适的词汇。详细可参考 Closing issues via commit messages

此外,在回复评审人意见时,请您遵守以下约定:

1)官方维护人员的每一个 review 意见都希望得到回复,这样会更好地提升开源社区的贡献。

  • 对评审意见同意且按其修改完的,给个简单的 Done 即可;
  • 对评审意见不同意的,请给出您自己的反驳理由。

2)如果评审意见比较多,

  • 请给出总体的修改情况。
  • 请采用 start a review 进行回复,而非直接回复的方式。原因是每个回复都会发送一封邮件,会造成邮件灾难。

二、总结

  • 开源社区依赖于众多开发者与用户的贡献和反馈,在这里感谢与期待大家向 PaddleVideo 提出宝贵的意见与 Pull Request ,希望我们可以一起打造一个领先实用全面的视频理解代码仓库!

三、参考文献

  1. PaddlePaddle本地开发指南
  2. 向开源框架提交pr的过程