贡献代码

PaddleHub非常欢迎贡献者。

首先,如果有什么不确定的事情,可随时提交问题或拉取请求。 不会有人因此而抱怨。我们会感激任何形式的贡献,不想用一堆规则来阻止这些贡献。

本文档包括了所有在贡献中需要注意的要点,会加快合并代码、解决问题的速度。

查看概览来初步了解。

下面是一些简单的贡献指南。

提交问题

当你使用PaddleHub遇到问题时,可以通过提交issue来反馈。

在提出问题时,请说明以下事项:

  • 按照问题模板的内容来填写问题细节,以便评审者查找问题原因。

  • 出现问题的场景 (尽量详细,以便重现问题)。

  • 错误和日志消息。

  • 其它可能有用的细节信息。

提交新功能建议/BUG修复

  • 在适配使用场景时,总会需要一些新的功能。 可以加入新功能的讨论,也可以直接提交新功能的Pull-Request请求。

  • 在自己的 github 账户下 fork PaddleHub(https://github.com/PaddlePaddle/PaddleHub)。 在 fork 后, 利用git工具(add, commit, pull, push)提交PR。 然后就可以提交拉取请求了。

如何提PR,参考下列步骤:

第一步:将自己目录下PaddleHub远程仓库clone到本地:

  1. https://github.com/USERNAME/PaddleHub

第二步:切换到远程分支develop

  1. git checkout develop

第三步:基于远程分支develop新建本地分支new-feature

  1. git checkout -b new-feature

第四步:使用pre-commit钩子

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

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

  1. pip install pre-commit
  2. pre-commit install

第五步:在new-feature分支上开发你的需求,提交你的更改

  1. git commit -m "add new feature"

第六步:在准备发起Pull Request之前,需要同步原仓库(https://github.com/PaddlePaddle/PaddleHub )最新的代码。

通过 git remote 查看当前远程仓库的名字。

  1. git remote
  2. origin
  3. git remote -v
  4. origin https://github.com/USERNAME/PaddleHub (fetch)
  5. origin https://github.com/USERNAME/PaddleHub (push)

这里 origin 是自己用户名下的PaddleHub,接下来创建一个原始PaddleHub仓库的远程主机,命名为 upstream。

  1. git remote add upstream https://github.com/PaddlePaddle/PaddleHub
  2. git remote
  3. origin
  4. upstream

获取 upstream 的最新代码并更新当前分支。

  1. git fetch upstream
  2. git pull upstream develop

第七步:推送本地分支new-feature到自己的PaddleHub库

  1. git push origin new-feature

这样你的PaddleHub库的new-feature分支包含了你的最新更改,点击上面的“pull request”就可以推送请求了。

如果评审人员给出了反馈需要继续修正代码,可以从第五步重新开始,这样所有的提交都会显示到同一个pull request中。

代码风格和命名约定

  • PaddleHub 遵循 PEP8 的 Python 代码命名约定。在提交拉取请求时,请尽量遵循此规范。 可通过flake8pylint的提示工具来帮助遵循规范。

文档

文档使用了 sphinx 来生成,支持 MarkdownreStructuredText 格式。 所有文档都在 docs/ 目录下。

  • 在提交文档改动前,请先在本地生成文档cd docs/ && make clean && make html,然后,可以在 docs/_build/html 目录下找到所有生成的网页。 请认真分析生成日志中的每个 WARNING,这非常有可能是或空连接或其它问题。

  • 需要链接时,尽量使用相对路径