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.

Guidelines

• Submitting a Pull Request
• Resolving a Conflict with the Master
• Combining Multiple Commits
• What Is the Consequence of Forcing a Push?
• Document
• Test Cases
• Examples
• Tutorials
• Core Library
• Python Package
• R Package

Submitting a Pull Request

• Before submitting your contribution, rebase your code on the most recent version of the master:

    git remote add upstream https://github.com/dmlc/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.

Resolving a Conflict with the Master

• Rebase to the current master:

   # 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

• 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:

git add conflicted.py.

• Continue rebasing by using this command:

   git rebase --continue

• Finally push to your fork. You might need to force the push:

   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:

git config core.editor the-editor-you-like

• Assuming that you want to merge last the last three commits, type the following commands:

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:

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.

Documents

• Document are created with Sphinx and recommonmark.
• You can build documents locally to proof them.

Test Cases

• All of the test cases are in GitHub in 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
• If you have blog posts about MXNet or tutorials that use MXNet, please tell us and we'll add a link to them in the examples on GitHub.

Tutorials

Want to contribute an MXNet tutorial? To get started, download the tutorial template.

Core Library

• We follow the Google C++ Style Guide for C++ code.
• We 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.
• You can reproduce the linter checks by typing make lint.

R Package

Code Style

• Most of the C++ code in the R package relies heavily on 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:

make rcpplint

• If necessary, you can disable the linter warning on certain lines with // NOLINT(*) comments.

Auto-Generated API

• Many MXNet APIs are exposed dynamically from Rcpp.
• mx_generated.R is the auto-generated API and documents for these functions.
• Remake the file by typing the following command at root folder:

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:

make roxygen.

R Markdown Vignettes

R Markdown vignettes are located on GitHub in R-package/vignettes. These R Markdown files aren't compiled. We host the compiled version on doc/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 repo to the doc folder.
• Type the following command for the doc/R-package package:

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

make html

This prevents radically increasing the size of the repo with generated images sizes.