diff --git a/R-package/README.md b/R-package/README.md index a4c678a47df8..9f8dc4eb16cd 100644 --- a/R-package/README.md +++ b/R-package/README.md @@ -8,29 +8,4 @@ Bleeding edge Installation Contributor Guide for R ----------------------- -### Code Style -- Most C++ of R package heavily relies on [Rcpp](https://github.com/RcppCore/Rcpp). -- 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. - -### Auto Generated API -- Many mxnet API are exposed from Rcpp side in a dynamic way. -- The [mx_generated.R](R/mx_generated.R) is auto generated API and documents for these functions. -- You can remake the file by typing the following command at root folder -```bash -make rcppexport -``` -- This only need to be done periodically when there is update on dynamic functions. - -### Document -- The document is generated using roxygen2 -- You can type the following command to remake the documents at root folder. -```bash -make roxygen -``` +Checkout [Contributor Guideline](../doc/contribute.md#r-package) \ No newline at end of file diff --git a/doc/contribute.md b/doc/contribute.md index 39b16c8a47aa..a14d70710dcb 100644 --- a/doc/contribute.md +++ b/doc/contribute.md @@ -4,40 +4,131 @@ MXNet 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. -Code Style +Guidelines ---------- -- Follow Google C style for C++. -- We use doxygen to document all the interface code. -- We use numpydoc to document all the python codes. -- You can reproduce the linter checks by typing ```make lint``` +* [Submit Pull Request](#submit-pull-request) +* [Git Workflow Howtos](#git-workflow-howtos) +* [Document](#document) +* [Testcases](#testcases) +* [Examples](#cexamples) +* [Core Library](#core-library) +* [Python Package](#r-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/mxnet +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/mxnet +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 merge multiple commits +Sometimes we want to merge 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. -Contribute to Documents ------------------------ +Documents +--------- * The document is created using sphinx and [recommonmark](http://recommonmark.readthedocs.org/en/latest/) * You can build document locally to see the effect. -Contribute to Testcases ------------------------ +Testcases +--------- * All the testcases are in [tests](../tests) * We use python nose for python test cases and gtest for c++ unittests. -Contribute to Examples ----------------------- +Examples +-------- * Usecases and examples will be in [example](../example) * We are super excited to hear about your story, if you have blogposts, tutorials code solutions using mxnet, please tell us and we will add a link in the example pages. -Submit a Pull Request ---------------------- -* Before submit, please rebase your code on the most recent version of master, you can do it by +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 +- Most C++ of R package heavily relies on [Rcpp](https://github.com/RcppCore/Rcpp). +- 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 -git remote add upstream https://github.com/dmlc/mxnet -git fetch upstream -git rebase upstream/master +make rcpplint +``` +- When needed, you can disable the linter warning of certain line with ```// NOLINT(*)``` comments. + +### Auto Generated API +- Many mxnet API are exposed from Rcpp side in a dynamic way. +- The [mx_generated.R](R/mx_generated.R) is auto generated API and documents for these functions. +- You can remake the file by typing the following command at root folder +```bash +make rcppexport +``` +- This only need to be done periodically when there is update on dynamic functions. + +### Document +- The document is generated using roxygen2 +- You can type the following command to remake the documents at root folder. +```bash +make roxygen ``` -* 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)