Contribution methods¶

Code contribution¶

You have used Open3D. You are familiar with the Open3D C++ and/or Python interface(s). You want to contribute code for a new feature or a bug fix. The easiest way to start as a new contributor is to take an existing code snippet as a reference and write some code similar to it. Follow the procedure below.

Recommended procedure¶

Download, build from source, and familiarize yourself with Open3D
Read the Open3D style guide and install required tools
Check existing classes, examples, and related code
Fork Open3D on GitHub
Create new features in your fork. Do not forget unit tests and documentation. Double-check the Open3D style guide
Make a pull request to the master branch
Make sure your PR passes the CI tests. If it doesn’t, fix the code until it builds and passes the CI tests
Your PR will be assigned to reviewers
Engage with your reviewers during the review process. Address issues or concerns raised during the review. Don’t let the review die.

Congratulations, your pull request has been merged. You are now part of Open3D!

Dos¶

[DO] Follow the Open3D style guide and install the required tools

[DO] Use C++11 features when contributing C++ code. Use C++14 and C++17 features only when required

[DO] Remember to provide Python bindings when adding new C++ core functionalities

[DO] Use Python 3 when contributing Python code

[DO] Be aware of OS and compiler versions. Please check System requirements for details.

[DO] Provide suitable unit tests

- Your contribution must come with unit tests of the most important functionality

- If you are modifying existing code, make sure that the unit tests are updated accordingly

[DO] Use object-oriented design

[DO] Minimize dependencies. Do not pull in heavy dependencies. Make the code as self-contained as possible

[DO] Keep your pull request as small and self-contained as possible

[DO] Write simple code that is clean and easy to understand

[DO] Minimize redundancies in your implementation

[DO] Avoid “premature optimization” that may hinder code readability

Don’ts¶

[DON’T] Do not contribute Python 2.7 code. Python 2.7 has been deprecated

[DON’T] Do not break the library

- When submitting a pull request, make sure that CI is able to build your PR without any error or warning

- We know that eliminating all warnings can be hard. Please try. This increases stability and speeds up compilation

[DON’T] Do not create a massive pull request with dozens of commits and files

Code reviews¶

You want to contribute to Open3D by reviewing code. Your mission is to help developers comply with Open3D standards. If you are new to this, make sure you have a good understanding of code review. (See this excellent introduction.) Follow the procedure below.

Recommended procedure¶

Check the list of open pull requests and pick one that doesn’t yet have a reviewer. Leave a comment on the PR mentioning your interest: e.g., “I could help review this PR.”

A project maintainer will assign you to the PR as a reviewer

Use Reviewable to perform the code review

When you begin the review, post a comment to indicate that you have started: e.g., “Starting to review this PR.”

Make sure that CI is able to build the PR and that tests pass

For features that are not covered by tests and CI (e.g., visualizer), download the code, run it, and inspect

Look for unit tests. If unit tests are not provided, ask the author to add them

Check for good documentation: doxygen/docstring comments

Check for good design

Object-oriented design

Code is simple and clear without premature optimizations

The implementation is not redundant

Verify compliance with the Open3D style guide

Provide clear feedback to the author and make suggestions for improving the PR

If the PR gets frozen for a while (more than a week), ping the author to revive the process

When everything is correct, give your :LGTM:

Congratulations, you have improved Open3D with your review. You are now part of Open3D!

Dos¶

[DO] Uphold the highest standards of quality

[DO] Implement the Guiding principles

[DO] Help the code’s author improve their contribution

[DO] Point out algorithm/API/design/style/build/other issues that need to be improved

[DO] Make sure the contribution comes with documentation / updates documentation

Don’ts¶

[DON’T] Do not approve just to be nice. Do not compromise on quality. Do not compromise the Guiding principles of Open3D

Bug reports¶

You are using Open3D. You are not getting the results you want. You think there is a bug, or a missing feature. You want to get support. Good! Please follow the procedure below.

Recommended procedure¶

Check the Open3D GitHub repository to see if there is already a related issue

If there is an existing issue, add a comment explaining the problem you encountered

You can also join our discord channel to ask questions. Other community members may have encountered the same issue and may be able to provide a solution

If you cannot find an existing ticket, please file your bug report on the GitHub issues board. Your report should include the following elements:

A description of the problem

A description of your environment: OS, Python version, compiler, Open3D version, installation method.

A minimal example to reproduce the problem.

The obtained output. Feel free to include screenshots.

A description of the expected result.

The Open3D team will explicitly acknowledge the receipt of the bug report by commenting on the issue.

Congratulations, you have improved Open3D with your report. Thanks for making Open3D better!

Dos¶

[DO] Always include a minimal example that reproduces the error

[DO] Provide information about your environment, so that we can detect problems related to compilers, dependencies, etc.

[DO] Indicate the output you were expecting

- Sometimes there are misunderstandings and the library provides you with a different output than the expected one

Don’ts¶

[DON’T] Do not open a new issue without double-checking whether there is already an existing issue that deals with the same problem

Documentation¶

Recommended procedure¶

Follow the general code contribution guidelines
Follow the Build documentation instructions to build both C++ and Python documentation. Make sure you can view the generated local web pages with a browser
Adhere to the cases presented below
Iterate steps 2 and 3 to build the docs and see the generated results. Make sure the syntax is correct so that the expected web page is generated

Case 1: When documenting C++ code¶

In header files, use Doxygen syntax. In C++ header files we use the in-line style with /// for docstring blocks. Make sure to use Doxygen commands whenever possible. For instance, use brief to denote the brief summary, param to define a parameter, return to define the return value, p to reference a parameter, ref to reference another function, etc.
See the example this Calculator class:

class Calculator {
public:
    /// \brief Computes summation.
    ///
    /// Performs \p a plus \p b. Unlike \ref sub, \ref add is commutative.
    /// \param a LHS operand for summation.
    /// \param b RHS operand for summation.
    /// \return The sum of \p a and \p b.
    int add(int a, int b) { return a + b; }

    /// \brief Computes subtraction.
    ///
    /// If detailed description is needed, add a blank line after the "brief"
    /// section. Subtracts \p b from \p a.
    /// \param a LHS operand for subtraction.
    /// \param b RHS operand for subtraction.
    /// \return The difference of \p a and \p b.
    int sub(int a, int b) { return a - b; }
};

Add in-line comments to cpp files to explain complex or non-intuitive parts of your algorithm

Case 2: When documenting Python bindings¶

First, complete the Python binding code following the guides from Pybind11 Docs. Make sure to write the high-level docstrings for the classes and functions. Also use “param_name”_a to denote function parameters.
Use the docstring::ClassMethodDocInject() or docstring::FunctionDocInject() to insert parameter docs.
Example binding and docstrings for the Calculator class:

py::class_<Calculator> calculator(
            m, "Calculator",
            "Calculator class performs numerical computations.");
calculator.def("add", &Calculator::Add,
               "Performs ``a`` plus ``b``. Unlike "
               ":meth:`open3d.Calculator.sub`, "
               ":meth:`open3d.Calculator.add` is "
               "commutative.",
                            "a"_a, "b"_a);
calculator.def("sub", &Calculator::Add, "Substracts ``b`` from ``a``", "a"_a,
                            "b"_a);
docstring::ClassMethodDocInject(m, "Calculator", "add",
                                {{"a", "LHS operand for summation."},
                                 {"b", "RHS operand for summation."}});
docstring::ClassMethodDocInject(m, "Calculator", "sub",
                                {{"a", "LHS operand for subtraction."},
                                 {"b", "RHS operand for subtraction."}});

Case 3: When documenting pure Python code (no bindings)¶

Use standard docstring syntax as explained here and there.

Case 4: When adding a Python tutorial¶

Place your tutorial notebook within Open3D/examples/python
Inside Open3D/docs/tutorial, update the toctree directive within the appropriate index.rst file
Update the index.rst file to include your new tutorial

Note

When you commit a ipynb notebook file make sure to remove the output cells to keep the commit sizes small. You can use the script examples/python/jupyter_strip_output.sh for stripping the output cells of all tutorials.

Dos¶

[DO] Always use a spell checker when writing documentation (e.g. Grammarly).