MxNet系列——community——contribute

对MXNet做贡献

MXNet是由一群活跃的社区成员开发和使用的。请对其贡献，以改善它。
当你的补丁被合并时，别忘记将你的名字提交到 CONTRIBUTORS.md.

Guidelines

• 提交Pull请求
• 解决与Master的冲突问题
• 组合多个提交
• 强制推送的结果是什么?
• 文档
• 测试用例
• 例程
• 核心库
• Python库
• R包

提交Pull请求

• 在提交你的贡献前，在最新版的master上，git rebase 你的代码：

git remote add upstream https://github.com/dmlc/mxnetgit fetch upstreamgit rebase upstream/master

• 如果你有多个小的提交，将其合并成一个有意义的组 (先使用 git rebase，在使用 squash)。
• 发送pull请求。
• 修改自动检查报告的问题。
• 如果你正在对一个新模块做贡献，考虑在 tests 中添加一个测试用例。

解决与Master的冲突问题

• Rebase 到当前master分支：

# 前两行只需做一次。如果已经执行过，跳过即可。git remote add upstream https://github.com/dmlc/mxnetgit fetch upstreamgit rebase upstream/master

• Git 可能打印一些冲突，阻止合并。例如， conflicted.py。
  
  • 手动修改文件，以解决冲突。
  • 解决冲突后，使用下面的代码将其标记为已解决(resolved)：

git add conflicted.py.

• 使用下面的命令继续 rebase：

git rebase --continue

• 最终推送到你的fork。可能需要强制推送：

git push --force

组合多个提交

如果你正在提交多个commits，而后面的commits刚好修复（fix to）在前面的一个时，你可以将多个commits组合成一个有意义的组，然后在创建一个推送请求。

• 开始前，先配置Git的默认编辑器（如果之前没有配置过的话）：

git config core.editor the-editor-you-like

• 假定你希望合并最后3个 commits，执行下面的命令：

git rebase -i HEAD~3

• 出现一个文本编辑器，将第一个commit设置为 pick，后一个设置为 squash。

• 保存文件之后，会出现另一个文本编辑器，让你修改组合的commit的信息。

• 通过强制推送，将改变推送到你的fork。

git push --force.

强制推送的结果是什么?

由于我们改变了commit路径，之前的两个Tips需要强制推送。强制推送到你自己的fork是没有问题的，只有你自己的commit被改变了。

文档

• 文档是使用 Sphinx 和 recommonmark 创建的。
• 你可以在本地构建文档来证实。

测试用例

• 所有的测试用例都在GitHub中的 tests 目录。
• 我们使用 python nose 作为python测试用例，用 gtest 作为 c++ 单元测试。

例程

• 用例和例程在Git的 examples目录。
• 如果你有关于MXNet的帖子后使用MXNet的教程，请告知我们。我们将会在GitHub中的例子中添加一个链接指向你的博客。

核心库

• 对于 C++ 代码，我们遵循Google C++ 风格指南（Google C++ Style Guide）。
• 我们使用 doxygen 将接口代码进行文档化。
• 你可以通过 make lint 重新生成 linter checks。

Python库

• 总是以numpydoc的格式为新的函数添加 docstring。
• 你可以通过 make lint 重新生成 linter checks。

R包

代码风格

• R包中的绝大多数C++代码都严重地依赖 Rcpp。
• 对于 C++ 代码，我们遵循Google C++ 风格指南（Google C++ Style Guide）。 这使得我们能够与项目的其它部分保持一致。它也允许我们使用 linter 自动检查风格。
• 在根目录中运行下面的命令，以检查代码风格：

make rcpplint

• 如果有必要，你可以通过 // NOLINT(*) 注释，来取消linter警告。

自动生成的API

• 很多 MXNet APIs 动态地暴露于Rcpp。
• mx_generated.R 是对这些函数自动生成的API和文档。
• 通过执行下面的命令，Remake 文件：

make rcppexport

• 仅当动态函数有更新时，才使用这个命令。

API 文档

文档是由 roxygen2 生成的。在根目录中执行下面的代码，可以 remake 文档：

make roxygen.

R Markdown Vignettes

R Markdown vignettes 位于GitHub上的 R-package/vignettes 目录。
这些 R Markdown 文件并没有编译。编译过的版本放在 doc/R-package。

添加一个新的 R Markdown vignettes：

• 将原始的 R Markdown 文件添加到 R-package/vignettes。
• 修改 doc/R-package/Makefile，添加待构建的 Markdown 文件。
• 将 dmlc/web-data 仓库克隆到 doc 文件夹。
• 为 doc/R-package 中的文件，执行以下命令：

make the-markdown-to-make.md

• 这将会生成 markdown 和图片，并将它们放在 doc/web-data/mxnet/knitr。
• 修改 doc/R-package/index.md，使其指向生成的markdown。
• 将生成的图片添加到 dmlc/web-data 仓库。
  
  • 如果你已经将这个仓库克隆到doc目录下，使用 git add 即可。
• 为markdown和 dmlc/web-data 创建一个 pull 请求。
• 你可以使用以下命令在本地构建文档：

make html

这从根本上阻止了仓库增加（生成）图像大小的存储。