Contributing to Open3D¶
Know how to use Open3D;
Know basic development rules such as coding style, issues, and pull requests;
Be willing to follow the guidelines in this page.
Issues and pull requests¶
master branch is used only for stable development versions of Open3D. Any code change is made through four steps using the issues and pull requests system.
An issue is opened for a feature request or a bug fix.
A contributor starts a new branch or forks the repository, makes changes, and submits a pull request.
Code change is reviewed and discussed in the pull request. Modifications are made to address the issues raised in the discussion.
One of the admins merges the pull request to the master branch.
Code review is known to be the best practice to maintain the usability and consistency of a large project. Though it takes some time at the beginning, it saves a lot of time in the long run. For new contributors, it can be viewed as a training procedure, in which an experienced contributor, as a reviewer, walks the new contributor through everything he needs to know.
There is an exception for this rule. Small changes can be made directly to the
master branch, such as fixing typos, formatting documents, and fixing an obvious bug.
Maintain sanity of the project¶
Most importantly, do not break the build. Before submitting a pull request, make sure the project builds without any error or warning under the following toolchains:
Windows, Visual Studio 2017 or newer, CMake 3.1+
OS X, Clang included in the latest Xcode, CMake 3.1+
Ubuntu 16.04, GCC 5.x or newer, CMake 3.1+
For C++ code, it is recommended to use C++11 features. However, do not use C++14 or C++17 features since some of them are not properly supported by mainstream compilers.
For Python code, make sure it runs on both Python 2.7 and Python 3.x.
The easiest way to start coding as a new contributor is to take an existing code snippet as reference and write some code similar to it.
Consistent coding style is an important factor of code readability. Some principles:
Code itself is a document. Name functions and variables in a way they are self explanatory.
Be consistent with existing code and documents. Be consistent with C++ conventions.
Use common sense.
We generally follow the Google C++ Style Guide, with a few modifications:
Use 4 spaces for indent. Use two indents for a forced line break (usually due to the 80 character length limit).
#pragma oncefor header guard.
All Open3D classes and functions are nested in namespace
Avoid using naked pointers. Use
C++11 features are recommended.
Another good reading for modern C++ coding style is C++ Core Guidelines
Automated style Checker¶
Open3D’s CI checks for code formatting based on the style specified in
.clang-format for C++ files and
.style.yapf for Python files.
Please build the
CMake target before submitting a pull request, or use your editor’s
yapf integration to format the source code automatically.
clang-format versions may produce slightly different
formatting results. For standardization,
5.0 shall be used.
By default, the make system tries to detect either
clang-format from PATH.
# Ubuntu 14.04 sudo apt update sudo apt install wget software-properties-common -y sudo wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add - sudo apt-add-repository "deb http://apt.llvm.org/trusty/ llvm-toolchain-trusty-5.0 main" sudo apt update sudo apt install clang-format-5.0 -y clang-format-5.0 --version # Ubuntu 16.04 sudo apt update sudo apt install clang-format-5.0 clang-format-5.0 --version # Ubuntu 18.04 sudo apt update sudo apt install clang-format-5.0 clang-format-5.0 --version
curl https://raw.githubusercontent.com/intel-isl/Open3D-3rdparty/master/clang-format/clang-format%405.rb -o $(brew --repo)/Library/Taps/homebrew/homebrew-core/Formulafirstname.lastname@example.org brew install clang-format@5 clang-format --version # (Optional) If another clang-format version was previously installed, we can keep # both versions and switch the default to version 5 brew unlink clang-format brew link clang-format@5 # (Optional) If you'd like to uninstall brew uninstall clang-format@5
Alternatively, download the clang-5.0 macOS package from LLVM Download Page,
unzip and add the directory containing
Download clang-5.0 Windows package from LLVM Download Page. During
installation, select the option which allows adding clang toolchains to
PATH. After installation, open a CMD terminal and try
Checking clang-format version¶
After installation, check
clang-format’s version with
# In most cases clang-format --version # Or, when installed as clang-format-5.0, e.g. on Ubuntu clang-format-5.0 --version
and make sure that version
5.0 is installed.
We use YAPF for Python formatting.
Different YAPF versions may produce slightly different formatting results, thus
we choose version
0.28.0 as the standard version to be used.
Install YAPF with
# For Pip pip install yapf==0.28.0 # For conda conda install yapf=0.28.0
You can also download YAPF and install it from source.
Checking and applying format¶
Ubuntu & macOS¶
After CMake config, to check style, run
After CMake config, to apply proper style, run
After CMake config, to check style, run
cmake --build . --target check-style
After CMake config, to apply the proper style, run
cmake --build . --target apply-style