Languages

Only C++14 is allowed for production code. Python and Bash is allowed for tooling. Deviations need to be approved by the technical leads.

Commiting

The developer shall commit and push regularly to the server to avoid data loss.

IDEs

While we provide an ADE volume for Atom for convenince, no specific IDE is required to develop software for Autoware.Auto.

However, we recommend using an IDE that has good support for ROS 2, such as Atom, Visual Studio Code or CLion.

CCache

CCache should be used if no specific debugging task is done that CCache interferers with. It is enabled by adding the following to the .bashrc:

export CC="/usr/lib/ccache/gcc"

export CXX="/usr/lib/ccache/g++"

Set a large cache size to make it really effective: ccache --max-size=100G.

The following issue needs to be considered when using CCache:

It hides unused variables compiler warnings, which will then pop up in the CI. However, static code analysis should also catch these locally.

Preparations

Creating the workspace (skip this step if you already have one)

If you plan to use the ADE (which we highly encourage you to do), you'll first need an ADE home:

$ mkdir -p ~/adehome
$ cd ~/adehome
$ touch .adehome

Install ade-cli via pip:

$ pip3 install -U ade-cli

Clone the AutowareAuto project:

$ git clone https://gitlab.com/autowarefoundation/autoware.auto/AutowareAuto.git

Entering ADE

cd AutowareAuto
ade start --update
ade enter

Workflow

We follow the standard fork-and-pull model popularized by GitHub.

For a detailed description of this workflow, please see our workflow guide.

Initial Build

colcon build

Optional: Creating a new package

See https://index.ros.org//doc/ros2/Tutorials/Colcon-Tutorial/#create-your-own-package

Writing Code

Write your code. It is recommended to build you code after every few lines using colcon build to validate that your code compiles.

Optional: Running Executables

After adding an executable you can run it by invoking ros2 run package_name executable_name.

Writing Integration Tests

launch_testing, introduced in ROS 2 Dashing, is the recommended mechanism for writing integration tests.

Any package that has an executable will be required to have an accompanying integration test. The purpose of the integration test is to start the executable and ensure that it processes any input data correctly and produces outputs according to its specification.

For more information on integration testing, see this article on integration testing fundamentals.

Checking Quality of the Code

This section discusses our requirements for validating the quality of submitted code. A failed quality check will require that the code needs to be changed or more unit tests need to be added. Therefore one might need to go back to the previous section.

Coverage

For code coverage, we use the popular GNU tool lcov for generating statistics about line coverage.

For every merge request, we run our testsuite and report the percentage of lines covered. We aim at a 100% line coverage and continuously improve our testsuite to achieve that number. In particular, we do not accept changes that reduce the coverage value. If a merge request has a lower line coverage than master, we will request the contributor to add more unit tests.

The following commands, taken from our automated CI pipeline, are one example of how to generate a coverage report for Autoware.Auto. You can execute them in your Autoware.Auto workspace and confirm that the coverage value is sufficient before submitting your merge request. Note that this is not required, as the CI pipeline will produce a coverage report automatically for your merge request.

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug --ament-cmake-args -DCMAKE_CXX_FLAGS="$COVERAGE_FLAGS" -DCMAKE_C_FLAGS="$COVERAGE_FLAGS"
lcov --config-file .lcovrc --base-directory "$PWD" --capture --directory build -o lcov.base --initial
colcon test --abort-on-error
lcov --config-file .lcovrc --base-directory "$PWD" --capture --directory build -o lcov.test
lcov --config-file .lcovrc -a lcov.base -a lcov.test -o lcov.total
lcov --config-file .lcovrc -r lcov.total "*/AutowareAuto/install/*" "*/CMakeCCompilerId.c" "*/CMakeCXXCompilerId.cpp" "*_msgs/*" -o lcov.total.filtered
genhtml --config-file .lcovrc -p "$PWD" --legend --demangle-cpp lcov.total.filtered -o coverage

Static Code Analysis

Static code analysis should be run in the described order, as the analyses are ordered from a semantic focus to a syntactic focus.

Linting and formatting code

ament comes with extensions for linting and formatting soure code via cpplint and uncrustify.

In order to check that a C/C++ file (header or implementation) does not contain serious static errors, you can invoke ament_cpplint filename.

Additionally, to ensure that source files are formatted according to the ROS 2 style guidelines, type ament_uncrustify filename --reformat.

Documentation

To check that the code is properly documented and all documents are correctly linked run AutowareAuto/docs/.doxygen/build.py.

The generated documentation can be found in docs/_build/html/index.html.

Finalizing the Code

Running all Tests of a Package

To run all tests of the package you are working on, run colcon test --packages-select packagen_name. Afterwards, you will need to invoke colcon test-result --verbose to see more details of any tests that failed.

Cleaning up Commits

Commits should be explicit about the goal of the contribution.

Before merging a merge request, all commits will be squashed to maintain a clean commit log.

There are several options to cleanup your commits using rebasing:

Use the terminal: git rebase -i master.

To push your chances run git push -fpush which allows history changes introduced by rebasing.