MxNet系列——community——contribute

2023-05-16

博客新址: http://blog.xuezhisd.top
邮箱：xuezhisd@126.com

对MXNet做贡献

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

Guidelines

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

提交Pull请求

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

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

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

解决与Master的冲突问题

Rebase 到当前master分支：

# 前两行只需做一次。如果已经执行过，跳过即可。
git remote add upstream https://github.com/dmlc/mxnet
git fetch upstream
git 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

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

本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)

mxnet

community

contribute