146 lines
5.5 KiB
Markdown
146 lines
5.5 KiB
Markdown
Contribute to XGBoost
|
|
=====================
|
|
XGBoost has been developed and used by a group of active community members.
|
|
Everyone is more than welcome to contribute. It is a way to make the project better and more accessible to more users.
|
|
|
|
- Please add your name to [CONTRIBUTORS.md](../CONTRIBUTORS.md) after your patch has been merged.
|
|
- Please also update [NEWS.md](../NEWS.md) to add note on your changes to the API or added a new document.
|
|
|
|
Guidelines
|
|
----------
|
|
* [Submit Pull Request](#submit-pull-request)
|
|
* [Git Workflow Howtos](#git-workflow-howtos)
|
|
- [How to resolve conflict with master](#how-to-resolve-conflict-with-master)
|
|
- [How to combine multiple commits into one](#how-to-combine-multiple-commits-into-one)
|
|
- [What is the consequence of force push](#what-is-the-consequence-of-force-push)
|
|
* [Document](#document)
|
|
* [Testcases](#testcases)
|
|
* [Examples](#examples)
|
|
* [Core Library](#core-library)
|
|
* [Python Package](#python-package)
|
|
* [R Package](#r-package)
|
|
|
|
Submit Pull Request
|
|
-------------------
|
|
* Before submit, please rebase your code on the most recent version of master, you can do it by
|
|
```bash
|
|
git remote add upstream https://github.com/dmlc/xgboost
|
|
git fetch upstream
|
|
git rebase upstream/master
|
|
```
|
|
* If you have multiple small commits,
|
|
it might be good to merge them together(use git rebase then squash) into more meaningful groups.
|
|
* Send the pull request!
|
|
- Fix the problems reported by automatic checks
|
|
- If you are contributing a new module, consider add a testcase in [tests](../tests)
|
|
|
|
Git Workflow Howtos
|
|
-------------------
|
|
### How to resolve conflict with master
|
|
- First rebase to most recent master
|
|
```bash
|
|
# The first two steps can be skipped after you do it once.
|
|
git remote add upstream https://github.com/dmlc/xgboost
|
|
git fetch upstream
|
|
git rebase upstream/master
|
|
```
|
|
- The git may show some conflicts it cannot merge, say ```conflicted.py```.
|
|
- Manually modify the file to resolve the conflict.
|
|
- After you resolved the conflict, mark it as resolved by
|
|
```bash
|
|
git add conflicted.py
|
|
```
|
|
- Then you can continue rebase by
|
|
```bash
|
|
git rebase --continue
|
|
```
|
|
- Finally push to your fork, you may need to force push here.
|
|
```bash
|
|
git push --force
|
|
```
|
|
|
|
### How to combine multiple commits into one
|
|
Sometimes we want to combine multiple commits, especially when later commits are only fixes to previous ones,
|
|
to create a PR with set of meaningful commits. You can do it by following steps.
|
|
- Before doing so, configure the default editor of git if you haven't done so before.
|
|
```bash
|
|
git config core.editor the-editor-you-like
|
|
```
|
|
- Assume we want to merge last 3 commits, type the following commands
|
|
```bash
|
|
git rebase -i HEAD~3
|
|
```
|
|
- It will pop up an text editor. Set the first commit as ```pick```, and change later ones to ```squash```.
|
|
- After you saved the file, it will pop up another text editor to ask you modify the combined commit message.
|
|
- Push the changes to your fork, you need to force push.
|
|
```bash
|
|
git push --force
|
|
```
|
|
|
|
### What is the consequence of force push
|
|
The previous two tips requires force push, this is because we altered the path of the commits.
|
|
It is fine to force push to your own fork, as long as the commits changed are only yours.
|
|
|
|
Documents
|
|
---------
|
|
* The document is created using sphinx and [recommonmark](http://recommonmark.readthedocs.org/en/latest/)
|
|
* You can build document locally to see the effect.
|
|
|
|
Testcases
|
|
---------
|
|
* All the testcases are in [tests](../tests)
|
|
* We use python nose for python test cases.
|
|
|
|
Examples
|
|
--------
|
|
* Usecases and examples will be in [demo](../demo)
|
|
* We are super excited to hear about your story, if you have blogposts,
|
|
tutorials code solutions using xgboost, please tell us and we will add
|
|
a link in the example pages.
|
|
|
|
Core Library
|
|
------------
|
|
- Follow Google C style for C++.
|
|
- We use doxygen to document all the interface code.
|
|
- You can reproduce the linter checks by typing ```make lint```
|
|
|
|
Python Package
|
|
--------------
|
|
- Always add docstring to the new functions in numpydoc format.
|
|
- You can reproduce the linter checks by typing ```make lint```
|
|
|
|
R Package
|
|
---------
|
|
### Code Style
|
|
- We follow Google's C++ Style guide on C++ code.
|
|
- This is mainly to be consistent with the rest of the project.
|
|
- Another reason is we will be able to check style automatically with a linter.
|
|
- You can check the style of the code by typing the following command at root folder.
|
|
```bash
|
|
make rcpplint
|
|
```
|
|
- When needed, you can disable the linter warning of certain line with ```// NOLINT(*)``` comments.
|
|
|
|
### Rmarkdown Vignettes
|
|
Rmarkdown vignettes are placed in [R-package/vignettes](../R-package/vignettes)
|
|
These Rmarkdown files are not compiled. We host the compiled version on [doc/R-package](R-package)
|
|
|
|
The following steps are followed to add a new Rmarkdown vignettes:
|
|
- Add the original rmarkdown to ```R-package/vignettes```
|
|
- Modify ```doc/R-package/Makefile``` to add the markdown files to be build
|
|
- Clone the [dmlc/web-data](https://github.com/dmlc/web-data) repo to folder ```doc```
|
|
- Now type the following command on ```doc/R-package```
|
|
```bash
|
|
make the-markdown-to-make.md
|
|
```
|
|
- This will generate the markdown, as well as the figures into ```doc/web-data/xgboost/knitr```
|
|
- Modify the ```doc/R-package/index.md``` to point to the generated markdown.
|
|
- Add the generated figure to the ```dmlc/web-data``` repo.
|
|
- If you already cloned the repo to doc, this means a ```git add```
|
|
- Create PR for both the markdown and ```dmlc/web-data```
|
|
- You can also build the document locally by typing the followig command at ```doc```
|
|
```bash
|
|
make html
|
|
```
|
|
The reason we do this is to avoid exploded repo size due to generated images sizes.
|