为 XGBoost 做贡献

为 XGBoost 做贡献

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

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

指导方针

提交 Pull Request
Git 工作流程
文档
测试用例
例子
核心库
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 爆炸。

开发和破解 XGBoost - 为 XGBoost 做贡献