Contribute to MXNet

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 after your patch has been merged.

Submit Pull Request

  • Before submit, please rebase your code on the most recent version of master, you can do it by
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

Git Workflow Howtos

How to resolve conflict with master

  • First rebase to most recent 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
  • 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
git add conflicted.py
  • Then you can continue rebase by
git rebase --continue
  • Finally push to your fork, you may need to force push here.
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.
git config core.editor the-editor-you-like
  • Assume we want to merge last 3 commits, type the following commands
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.
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
  • You can build document locally to see the effect.

Testcases

  • All the testcases are in tests
  • We use python nose for python test cases and gtest for c++ unittests.

Examples

  • Usecases and examples will be in 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.

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.
  • 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.
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 is auto generated API and documents for these functions.
  • You can remake the file by typing the following command at root folder
make rcppexport
  • This only need to be done periodically when there is update on dynamic functions.

API Document

  • The document is generated using roxygen2
  • You can type the following command to remake the documents at root folder.
make roxygen

Rmarkdown Vignettes

Rmarkdown vignettes are placed in R-package/vignettes These Rmarkdown files are not compiled. We host the compiled version on doc/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 repo to folder doc
  • Now type the following command on doc/R-package
make the-markdown-to-make.md
  • This will generate the markdown, as well as the figures 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 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
make html

The reason we do this is to avoid exploded repo size due to generated images sizes.

© 2015-2016 DMLC. All rights reserved.