See also: development guide.

Contribution Standards

New Features or Major Updates

Before you start coding make sure there is a Github issue that corresponds to your contribution:

- Overview of the general approach
- List of API changes (changed interfaces, new and deprecated configuration parameters, changed behavior, …)
- Main components and classes to be touched
- Known limitations of the proposed approach

A design document can be added by anybody, including the reporter of the issue or the person working on it.

Please check with community (by emailing the dev list) if a design document is required before starting to code on a major feature.  A design document must be accepted by the community with lazy consensus before a contribution will be added to MXNet’s code base. 

Core Library

- Follow the Google C++ Style Guide for C++ code.
- Use doxygen to document all of the interface code.
- Use RAII to manage resources, including smart pointers like shared_ptr and unique_ptr as well as allocating in constructors and deallocating in destructors. Avoid explicit calls to new and delete when possible. Use make_shared and make_unique instead.
- To reproduce the linter checks, you can rely on the CI script. Take a look at the README in the ci folder and run python ci/build.py -R --platform ubuntu_cpu /work/runtime_functions.sh sanity_check

Python Package

- Always add docstring to the new functions in numpydoc format.
- To reproduce the linter checks, you can rely on the CI script or use pylint. Take a look at the README in the ci folder and run python ci/build.py -R --platform ubuntu_cpu /work/runtime_functions.sh sanity_check

New APIs

Make sure to add documentation with any code you contribute. Follow these standards:

API Documentation

  • Document are created with Sphinx and recommonmark.
  • Follow numpy doc standards. With the following caveats:
    • 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 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 , ROIPooling , Reshape.

Test Cases

  • All of the tests can be found in /tests.
  • We use pytest for Python test cases, and gtest for C++ unit tests.

Examples

  • Use cases and examples in /examples.
  • Many tutorials that are in Jupyter notebook format are in /docs/tutorials.
  • If you write a blog post or tutorial about or using MXNet, please tell us by writing to dev@mxnet.apache.org. We regularly feature high-quality contributed content from the community.

Guidelines for Reviewers/Committers

  1. As a reviewer you have the responsibility to ensure contributions meet the quality bar. This means you should try and ensure:

    1. Contributions are inline with the overall code architecture.

    2. Contributions are not lowering the overall code maintainability i.e. documentation and unit tests are not missing.

    3. If you don’t understand the logic/flow now, chances are it won’t automatically get better in the future. So feel free to push back if code/logic is hard to follow. Ask to include comments clarifying implementation details whenever necessary.

  2. When providing feedback or when seeking clarification, be clear. Don’t assume the PR owner knows exactly what is in your mind.

  3. If you decide to close a PR without merging, get an ack from the PR owner that that is indeed the right next step.

  4. It is NOT recommended for a committer to merge pull requests that the committer authored. Instead the committer MUST get at least one approval from another committer to merge his/her pull request. 

  5. When you update a pull request with upstream, you MUST use rebase to ensure that the pull request is easy to review by the community. See the how-to link here: https://mxnet.incubator.apache.org/community/contribute.html

Deleting Comments on GitHub

GitHub issues and pull requests allow a user with "Write" permissions to delete another's comment. The Apache Way yearns for openness in all situations, deleting a comment is rarely the right thing to do. 

If a comment does need deleting, most likely because it does not adhere to our Code of Conduct, then the PMC as a whole should discuss and vote on the deletion. If a comment needs to be deleted quickly, then either the PMC Chair (or while in the Incubator a Mentor) should make that decision.  

Related Articles


  • No labels