Skip to content

为 XGBoost 做贡献

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

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

指导方针

提交 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 爆炸。



回到顶部