The following guide will help you with the process for contributing code to the MXNet project.

Step-by-step guide

  1. Fork the Github repository at https://github.com/apache/incubator-mxnet if you haven’t already. Follow the build from source instructions for your platform.
  2. Clone your fork using the 'git clone -–recursive' option, create a new branch, push commits to the branch.
  3. Coding and Documenting
    1. Review the contribution standards for the kind of contribution you are making.
    2. Consider whether documentation or tests need to be added or updated as part of the change, and add them as needed.
    3. When adding new APIs or modifying existing APIs:

      1. Make sure to add/update appropriate API documentation.

      2. If adding a new API, include in the API documentation sample code that shows how to use the API.

      3. If modifying an existing API, make sure that API documentation and code samples are still accurate after your changes.

      4. Changes that add new functionality or extend existing functionality should always be accompanied by unit tests that exercise that functionality.

      5. When updating code that is performance sensitive, include in the PR description details on how you tested your changes from a performance standpoint.

  4. Open a pull request against the master branch of apache/mxnet. (Only in special cases would the PR be opened against other branches.) Detailed info creating a pull request and handling merge conflicts are in the following section.
    1. The PR title should be of the form [MXNET-xxxx] Title, where MXNET-xxxx is the relevant JIRA number, title may be the JIRA’s title or a more specific title describing the PR itself.
      1. only the very tiny fix, e.g. fix a typo, remove some unused variables, or the hotfix which brings the broken build back to track, can be filed without JIRA ID in title,
    2. If the pull request is still a work in progress, and so is not ready to be merged, but needs to be pushed to Github to facilitate review, then add [WIP] after the component.
    3. Consider identifying committers or other contributors who have worked on the code being changed. Find the file(s) in Github and click “Blame” to see a line-by-line annotation of who changed the code last. You can add @username in the PR description to ping them immediately.
    4. Please state that the contribution is your original work and that you license the work to the project under the project’s open source license.
  5. There is no need to be the Assignee of the related JIRA to work on it, though you are welcome to comment that you have begun work.
    1. The Jenkins automatic pull request builder will test your changes
    2. Jenkins will update the results of the test in the pull request
    3. Watch for the results, and investigate and fix failures promptly
      1. Fixes can simply be pushed to the same branch from which you opened your pull request
      2. Jenkins will automatically re-test when new commits are pushed
      3. If the tests failed for reasons unrelated to the change (e.g. Jenkins outage), you are supposed to ping the dev mail list about the outage or file a JIRA regarding the flaky test
    4. When you receive feedback for your PR, try and address the reviewer’s comments/concerns in a timely fashion. If you don’t have time to immediately address them, adding a short note to the PR about when you plan to update the PR will be helpful. Feel free to solicit help if you want others to pitch in.

How to Submit 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/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.

Note: If you are contributing a new module, consider adding a test case in tests.

Resolving a Conflict with 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/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:
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


Consequences of using --force

It's fine to force a push to your own fork, as long as only your commits are changed.


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