为 XGBoost 做贡献

XGBoost 已经被一群活跃的社区成员开发和使用。 欢迎每个人来做贡献。这是使项目更好，更方便用户使用的一种方法。

• 当你的补丁被 merged 后，请将您的名字添加到 CONTRIBUTORS.md 。
• 请同时更新 NEWS.md ，以便对 API 的更改添加注释或添加新文档。

指导方针

• 提交 Pull Request
• Git 工作流程
  • 如何解决与 master 的冲突
  • 如何将多个提交合并为一个
  • force push（强制 push）的后果是什么
• 文档
• 测试用例
• 例子
• 核心库
• Python 包
• R 包

提交 Pull Request

• 在提交之前，请将您的代码重新与最新版本的 master 上的代码做一次同步（rebase），您可以这么做

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

• 如果你有多个小提交，可以将它们 merge 到一起 (使用 git rebase 然后 squash) 成为更有意义的组。
• 发送 pull request!
  • 修复自动检查报告的问题
  • 如果您正在贡献一个新模块，请考虑在 tests 中添加一个测试用例

Git 工作流程

如何解决与 master 的冲突

• 首先 rebase 到最新的 master

# 做完一次后，可以跳过前两个步骤
git remote add upstream https://github.com/dmlc/xgboost
git fetch upstream
git rebase upstream/master

• git 可能会显示一些它不能合并的冲突，比如说 conflicted.py 。
  • 手动修改文件以解决冲突。
  • 解决冲突后，将其标记为已解决

git add conflicted.py

• 那么你可以继续 rebase 通过

git rebase --continue

• 最后 push 到你的 fork 上，你可能需要在这里 force push（强制 push）。

git push --force

如何将多个提交合并为一个

有时候我们想要合并多个 commits（提交），特别是当以后的 commits（提交）只能修复以前的提交时，创建一个有意义的提交集合的 PR 。你可以通过以下步骤来完成。

• 在此之前，如果您之前没有这样做，请配置 git 的默认编辑器。

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

• 假设我们要 merge 最后 3 个 commits，请输入以下命令

git rebase -i HEAD~3

• 它会弹出一个文本编辑器。将第一个 commit 设置为 pick ，将后一个 commit 更改为 squash 。
• 保存文件之后，会弹出另一个文本编辑器，要求你修改合并的 commit message（提交信息）。
• 将更改 push 到你的 fork ，你需要强制 push（force push）。

git push --force

force push（强制 push）的后果是什么

前两个提示需要强制 push（force push），这是因为我们改变了提交的路径。 只要提交的内容只属于你自己的内容，就可以强制 push 到自己的 fork 。

文档

• 该文档是使用 sphinx 和 recommonmark 创建的。
• 你可以在本地构建文档以查看效果。

测试用例

• 所有的测试用例在 tests 中。
• 我们使用 python nose 进行 python 测试用例。

示例

• 用例和示例将在 demo 中
• 我们非常高兴听到您的故事，如果您有使用 xgboost 的博客，教程代码解决方案，请告诉我们，我们将在示例页面中添加一个链接。

核心库

• 遵循 C++ 的 Google C 的风格。
• 我们使用 doxygen 来记录所有的接口代码。
• 你可以通过输入 make lint 来重新产生 linter 。

Python 包

• 总是将 docstring（文档字符串） 添加到 numpydoc 格式的新函数中。
• 你可以通过输入 make lint 来重新生成 linter 。

R 包

代码风格

• 我们在 C++ 代码上遵循 Google 的 C++ 风格指南。
  • 这主要与项目的其他部分保持一致。
  • 另一个原因是我们可以用 linter 自动检查样式。
• 你可以通过在根文件夹中键入以下命令来检查代码的样式。

make rcpplint

• 在需要的时候，你可以用 // NOLINT(*) 注释来禁用某行的 linter 警告。

Rmarkdown Vignettes

Rmarkdown vignettes 放置在 R-package/vignettes 这些 Rmarkdown 文件不被编译。我们在 doc/R-package 上托管编译的版本。

按照以下步骤添加一个新的 Rmarkdown vignettes:

• 将原始的 rmarkdown 添加到 R-package/vignettes
• 修改 doc/R-package/Makefile 来添加要构建的 markdown 文件
• Clone dmlc/web-data 仓库到 doc 文件夹中
• 现在在 doc/R-package 上输入以下命令

make the-markdown-to-make.md

• 这将生成 markdown 以及 figure（图形）到 doc/web-data/xgboost/knitr 中
• 修改 doc/R-package/index.md 来指向生成的 markdown 。
• 将生成的 figure 添加到 dmlc/web-data 仓库。
  • 如果你已经将 repo clone 到 doc，这意味着一个 git add
• 为 markdown 和 dmlc/web-data 创建 PR
• 你也可以通过在 doc 处输入以下命令在本地生成文档

make html

我们这样做的原因是为了避免由于生成的图像 size 导致 repo 的 size 爆炸。