| # Contribute to MXNet |
| |
| MXNet has been developed and is used by a group of active community members. |
| Please contribute to improve the project. |
| After your patch has been merged, remember to add your name to [CONTRIBUTORS.md](https://github.com/apache/incubator-mxnet/blob/master/CONTRIBUTORS.md). |
| |
| ## Code Contribution |
| |
| ### Core Library |
| |
| - Follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) for C++ code. |
| - Use doxygen to document all of the interface code. |
| - To reproduce the linter checks, type ```make lint```. |
| |
| ### Python Package |
| |
| - Always add docstring to the new functions in numpydoc format. |
| - To reproduce the linter checks, type ```make lint```. |
| |
| ### R Package |
| |
| #### Code Style |
| - Most of the C++ code in the R package relies heavily on [Rcpp](https://github.com/RcppCore/Rcpp). |
| - We follow the Google C++ Style Guide for C++ code. This allows us to maintain consistency with the rest of the project. It also allows us to check style automatically with a linter. |
| - To check the code style, type the following command at the root folder: |
| ```bash |
| make rcpplint |
| ``` |
| - If necessary, disable the linter warning on certain lines with ```// NOLINT(*)``` comments. |
| |
| #### Auto-Generated API |
| - Many MXNet APIs are exposed dynamically from Rcpp. |
| - mxnet_generated.R is the auto-generated API and documents for these functions. |
| - Remake the file by typing the following command at root folder: |
| ```bash |
| make rcppexport |
| ``` |
| - Use this command only when there is an update to dynamic functions. |
| |
| #### API Document |
| The document is generated using roxygen2. To remake the documents in the root folder, use the following command: |
| ```bash |
| make roxygen. |
| ``` |
| |
| #### R Markdown Vignettes |
| R Markdown vignettes are located on GitHub in [R-package/vignettes](https://github.com/apache/incubator-mxnet/tree/master/R-package/vignettes). |
| These R Markdown files aren't compiled. We host the compiled version on [doc/R-package](https://github.com/apache/incubator-mxnet/tree/master/R-package/). |
| |
| To add a new R Markdown vignettes: |
| |
| * Add the original R Markdown file to ```R-package/vignettes``` |
| * Modify ```doc/R-package/Makefile``` to add the Markdown files to be built. |
| * Clone the [dmlc/web-data](https://github.com/dmlc/web-data) repo to the ```doc``` folder. |
| * Type the following command for the ```doc/R-package``` package: |
| ```bash |
| make the-markdown-to-make.md |
| ``` |
| * This generates the markdown and the figures and places them into ```doc/web-data/mxnet/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 have already cloned the repo to doc, use ```git add```. |
| * Create a pull request for both the markdown and ```dmlc/web-data```. |
| * You can also build the document locally with the following command: ```doc``` |
| ```bash |
| make html |
| ``` |
| |
| ### Test Cases |
| |
| * All of our tests can be found in the GitHub repo in [this directory](https://github.com/apache/incubator-mxnet/tree/master/tests). |
| * We use Python nose for python test cases, and gtest for C++ unit tests. |
| |
| ### Examples |
| |
| * Use cases and examples are on GitHub in [examples](https://github.com/apache/incubator-mxnet/tree/master/example) |
| * If you write a blog post or tutorial about or using MXNet, please tell us by creating an issue |
| in our github repo. We regularly feature high-quality contributed content from the community. |
| |
| ## Standard for Contributing APIs |
| |
| Make sure to add documentation with any code you contribute. Follow these standards: |
| |
| ### API Documentation |
| * Document are created with Sphinx and [recommonmark](http://recommonmark.readthedocs.org/en/latest/). |
| * Follow [numpy doc standards](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard) and |
| some changes we made [MXNet doc standards](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard). |
| * If an API is implemented in Python or has a wrapper defined, the documentation and the examples reside |
| where the function is defined in `.py` file in [python/mxnet](https://github.com/apache/incubator-mxnet/tree/master/python/mxnet) folder. Same goes for other languages. |
| * If the API is dynamically generated from the MXNet backend, the documentation is in the C++ code(.cc |
| file) where the operator is registered in describe method of the `NNVM_REGISTER_OP`. The file and line |
| number for the function is usually printed with the API documentation on mxnet.io. |
| * A clear and concise description of the function and its behavior. |
| * List and describe each parameter with the valid input values, whether it is required or optional, |
| and the default value if the parameter is optional. |
| * Add an example to help the user understand the API better. If the example can be language-neutral |
| or is conceptual, add it in the C++ documentation. Make sure your example works |
| by running a Python version of the example. |
| * If a concrete and simple language-specific example can further clarify the API and the API arguments, add the |
| example in language-specific files. |
| * Refer to these examples for guidance:- [Embedding](http://mxnet.io/api/python/ndarray.html#mxnet.ndarray.Embedding) , [ROIPooling](http://mxnet.io/api/python/ndarray.html#mxnet.ndarray.ROIPooling) , [Reshape](http://mxnet.io/api/python/ndarray.html#mxnet.ndarray.Reshape). |
| |
| ### Testing and Rendering |
| * Make sure not to break any coding standards. Run |
| ```bash |
| make lint |
| ``` |
| * You can build documents locally to proof them. |
| |
| ## Guidelines to submit a Pull Request |
| * Before submitting your contribution, rebase your code on the most recent version of the master: |
| |
| ```bash |
| git remote add upstream https://github.com/apache/incubator-mxnet |
| git fetch upstream |
| git rebase upstream/master |
| ``` |
| * If you have multiple small commits, |
| merge them into meaningful groups (use ```git rebase``` then ```squash```). |
| * Send the pull request. |
| * Fix problems reported by automatic checks. |
| * If you are contributing a new module, consider adding a test case in [tests](https://github.com/apache/incubator-mxnet/tree/master/tests). |
| |
| ### Resolving a Conflict with the Master |
| |
| * Rebase to the current master: |
| |
| ```bash |
| # The first two steps can be skipped after you do it once. |
| git remote add upstream https://github.com/apache/incubator-mxnet |
| git fetch upstream |
| git rebase upstream/master |
| ``` |
| |
| * Git might show some conflicts that prevent merging, for example, ```conflicted.py```. |
| * Manually modify the file to resolve the conflict. |
| * After you resolve the conflict, mark it as resolved by using: |
| |
| ```bash |
| git add conflicted.py. |
| ``` |
| |
| * Continue rebasing by using this command: |
| |
| ```bash |
| git rebase --continue |
| ``` |
| |
| * Finally push to your fork. You might need to force the push: |
| |
| ```bash |
| git push --force |
| ``` |
| |
| ### Combining Multiple Commits |
| If you are submitting multiple commits with later commits that are just fixes to previous ones, you can combine commits into meaningful groups before creating a push request. |
| |
| * Before doing so, configure Git's default editor if you haven't already done that: |
| |
| ```bash |
| git config core.editor the-editor-you-like |
| ``` |
| * Assuming that you want to merge last the last three commits, type the following commands: |
| |
| ```bash |
| git rebase -i HEAD~3 |
| ``` |
| |
| * In the text editor that appears, set the first commit as ```pick```, and change later ones to ```squash```. |
| |
| * After you save the file, another text editor will appear and ask you to modify the combined commit message. |
| |
| * Push the changes to your fork by forcing a push: |
| |
| ```bash |
| git push --force. |
| ``` |
| |
| ### What Is the Consequence of Forcing a Push? |
| The previous two tips require forcing a push because we altered the path of the commits. |
| It's fine to force a push to your own fork, as long as only your commits are changed. |