How to Contribute Code · Apache SINGA

Coding Style

The SINGA codebase follows the Google Style for both CPP and Python code.

A simple way to enforce the Google coding styles is to use the linting and formating tools in the Visual Studio Code editor:

Once the extensions are installed, edit the settings.json file.

{
  "[cpp]": {
    "editor.defaultFormatter": "xaver.clang-format"
  },
  "cpplint.cpplintPath": "path/to/cpplint",

  "editor.formatOnSave": true,
  "python.formatting.provider": "yapf",
  "python.linting.enabled": true,
  "python.linting.lintOnSave": true,
  "clang-format.language.cpp.style": "google",
  "python.formatting.yapfArgs": ["--style", "{based_on_style: google}"]
}

Depending on your platform, the user settings file is located here:

Windows %APPDATA%\Code\User\settings.json
macOS "$HOME/Library/Application Support/Code/User/settings.json"
Linux "$HOME/.config/Code/User/settings.json"

Configurations are specified in corresponding config files. And these tools would look up for configuration files in the root of the project automatically, e.g. .pylintrc.

Tool Installation

It is ideal when all the contributors uses the same version of code formatting tool (clang-format 9.0.0 and yapf 0.29.0), so that all code formatting in different PRs would be identical to get rid of github pull request conflicts.

First, install LLVM 9.0 which provides clang-format version 9.0.0. The download page of LLVM is:

LLVM
- On Ubuntu
```
sudo apt-get install clang-format-9
```
- On Windows. Download the pre-built package and install

Second, install cpplint, pylint and yapf

Ubuntu or OSX:

$ sudo pip install cpplint
$ which cpplint
/path/to/cpplint

$ pip install yapf==0.29.0
$ pip install pylint

Windows: Install Anaconda for package management.

$ pip install cpplint
$ where cpplint
C:/path/to/cpplint.exe

$ pip install yapf==0.29.0
$ pip install pylint

Usage

After the configuration, linting should be automatically applied when editing source code file. Errors and warnings are listed in Visual Studio Code PROBLEMS panel.
Code Formatting could be done by bringing up Command Palette(Shift+Ctrl+P in Windows or Shift+Command+P in OSX) and type Format Document.

Submission

You need to fix the format errors before submitting the pull requests.

Developing Environment

Visual Studio Code is recommended as the editor. Extensions like Python, C/C++, Code Spell Checker, autoDocstring, vim, Remote Development could be installed. A reference configuration (i.e., settings.json) of these extensions is here.

If you update the CPP code, you need to recompile SINGA from source. It is recommended to use the native building tools in the *-devel Docker images or conda build.

If you only update the Python code, you can install SINGAS once, and then copy the updated Python files to replace those in the Python installation folder,

cp python/singa/xx.py  <path to conda>/lib/python3.7/site-packages/singa/

Workflow

Please refer to the git workflow page.