Guidelines and Best Practices

Table of Contents

• Contribution Workflow
• Guidelines for General Code Development
  • Building
  • Committing
  • Cross-platform Compatibility
  • Documentation
  • Formatting
  • Code Coverage
  • C++ Resources
• Guidelines for ROS Development
  • Creating a New Package
  • 2-Tier Development Pattern
  • Naming in Autoware.Auto
  • On Topics and Parameters
    • Parameter File Syntax
  • ROS Components
    • Minimal CMake Example
    • Minimal Package.xml Example
  • Resources

Contribution Workflow

1. Create an issue defining your intended contribution
   1. Use one of the provided templates by selecting one from the drop-down list.
   2. Select yourself in the Assignee field.
   3. If you have permissions to do so, assign to an appropriate milestone. If you do not have permissions, mention a maintainer in the issue for milestone assignment.
   4. The issue template you choose will assign one appropriate label for the issue type (bug, discussion, feature, or improvement). Assign any additional labels from the available list that you feel are appropriate for the issue's status or other attributes.
2. Create a fork
   1. For more information about the fork-and-pull model, see the Develop in a Fork page.
3. Write code
4. Create a merge request
   1. For more information about the fork-and-pull model, see the Develop in a Fork page.
5. Finish a merge request
   1. In order for a merge request to be merged to Autoware.Auto, it must meet the following criteria:
      • All discussions on the merge request must be resolved.
      • All items of the merge-request checklist are checked off.
      • It must be approved by at least one maintainer.
      • CI jobs for the merge request must have passed successfully.
   2. If you have permissions, the "Merge" button will show up automatically on your merge request once the above criteria are met. If you do not have permissions and the above criteria are met, assign the merge request to a maintainer.
   3. If another merge request is merged before yours, your merge request is out of date and needs to be rebased and CI needs to run again.

Guidelines for General Code Development

Only C++14 and below is allowed for functional code. Python 3.7+ and Bash are allowed for tooling. CMake is the preferred build system, it should integrate with Colcon. Deviations need to be approved by the maintainers.

The requirements for C++14 and Python 3.7+ align with compiler and tooling support found in ROS Foxy. This may change in the future as new OS or ROS environments are targeted; see System Dependencies and Target Environments for details.

Building

See Building.

Committing

Developers should commit and push regularly to GitLab to avoid data loss. Commit messages should follow common standards as laid out in this post. In summary,

1. Write your commit message in the imperative

1. In the mandatory first line, summarize what the functional change is, not why it is introduced

1. Optionally add more details separated by a blank line

As a general recommendation, add a reference to the issue in the commit message so it is easier for others in the future to get more context about the changes in the commit. If the commit doesn't refer to a particular issue but only touches a particular package or aspect, add a reference to that.

Example summary line referring to issue #716:

[716] Expand contributor guidelines

Example summary line without an issue:

[CI] Disable flaky tests in foo and bar packages

There is assistance via git hooks to help with commit messages. Navigate to .git/hooks in the checkout of Autoware.Auto, then:

ln -s ../../.git-hooks/prepare-commit-msg  # prepend issue number
ln -s ../../.git-hooks/commit-msg          # check formatting of commit message

Cross-platform Compatibility

It is preferred to use cross-platform solutions for system-level function calls whenever possible. While the C++ standard library should be used for as many tasks as possible, some functions (such as std::filesystem) are not available in C++14 in cross-platform implementations. This usually means utilizing libraries like asio for networking tasks and a std::filesystem shim for filesystem navigation is preferred to creating platform-specific implementations.

Documentation

To check that the code is properly documented and all documents are correctly linked, you can run AutowareAuto/docs/.doxygen/build.py. The generated documentation can be found in AutowareAuto/docs/_build/html/index.html. For more details see the documentation guide.

Formatting

Autoware.Auto follows ROS recommendations for code style and formatting. See the Coding Style and Language Versions entry for C++ or the Coding Style and Language Versions entry for Python for more information. We enforce these guidelines using linters provided with ament as far as possible. All packages should have the following in their package.xml files:

<test_depend>ament_lint_auto</test_depend>
<test_depend>ament_lint_common</test_depend>

In addition, the following should be in the package's CMakeLists.txt (extended with other tests):

if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  ament_lint_auto_find_test_dependencies()
endif()

In CI, merge requests fail if they introduce improperly formatted code. To avoid that, format the C++ code locally with

ament_uncrustify --reformat file.cpp         # update single file in place
ament_uncrustify --reformat path/to/pkg_foo  # update all C++ source files in package

With the above CMake setup, run all linters together with all other tests of a package as described in the Running Tests section or run a specific linter; e.g.,

ament_cpplint path/to/pkg_foo

Tools such as CLion can parse the output of the previous command and provide fast navigation to offending lines in the code.

To lint the code automatically before each commit, activate the pre-commit hook. From the repository base directory, do:

cd .git/hooks
ln -s ../../.git-hooks/pre-commit

Code Coverage

For code coverage, we use the popular GNU tool lcov for generating statistics about line coverage. For every merge request, we run our test suite and report the percentage of lines covered. We aim for a 100% line coverage and continuously improve our test suite 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 tests.

The coverage report for the latest successful CI run on the master branch is available here.

Check Coverage for details to create that report manually.

The articles on How to Write Tests and Measure Coverage and How to Write Integration Tests have further details on writing tests.

C++ Resources

• cppreference.com
• C++ Core Guidelines

Guidelines for ROS Development

In general, Autoware.Auto follows the ROS 2 Developer Guide for contributions, except where noted. Some special items of note that are not described in the ROS 2 Developer Guide are listed below.

Creating a New Package

Basic instructions for creating a new ROS 2 package can be found in this tutorial. In Autoware.Auto, much of the boilerplate code can be automatically generated by utilizing the autoware_auto_create_pkg tool.

For more information on using the tool, see autoware_auto_create_pkg.

2-Tier Development Pattern

In all but the most trivial utilities, it is best to implement a code pattern with at least two tiers of abstraction which would look something like:

1. A "core," pure C++ class which performs all basic algorithmic and utility functions which are not ROS-related.

   This class may use ROS utilities such as logging or message structures, but such use must be justified in terms of why it cannot be done via the class's external interface (e.g. the enclosing node uses information obtained via the class's external interface to populate log messages).

2. A "ROS Node" or "ROS Component" class which inherits from rclcpp::Node or a subclass, handles all ROS-specific functions.

   This class should instantiate the class defined in 1. and register the node as a component, so it can be created with launch files.

In the rare case that fine-grained control over execution is desired, create a main function in a separate file with a ROS Executor to control provision of execution time of the node in some way (e.g. through calling spin()).

This design pattern helps to promote separation of concerns and code re-use. The core and the ROS node(s) can be implemented in separate packages; e.g. foo and foo_nodes. There are some trivial cases where a simple ROS Node that does not require a "core" are acceptable but these should be the exception, not the rule.

Naming in Autoware.Auto

The Naming Guidelines provide for standard, reliable naming and namespacing conventions which should be used in all Autoware.Auto packages.

On Topics and Parameters

In most cases, topics should receive a default name in code and be remapped if needed. Providing topic names as ROS parameters is an anti-pattern, with few exceptions.

Required parameters should not have default values but fail during construction if no value is provided.

Parameter File Syntax

To avoid the need to change parameter files based on the namespacing or node name of a node, use the "double-star" syntax. e.g.:

/**:
  ros__parameters:
    param1: value

The above parameter file can be passed to any node regardless of namespace or name and the parameters will populate those of the node if the declared parameters match those in the file.

ROS Components

As of ROS Dashing, the recommended way to write Nodes in ROS 2 is using Components. For more information about components and their use, see the ROS Composition Guide. To implement your node as a Component, it must conform to the items below (using ListenerNode as an example):

• Must inherit from rclcpp::Node or a subclass (such as rclcpp::LifecycleNode)
• Must use a single-argument constructor in the form of:

namespace composition_example
{
class ListenerNode: public rclcpp::Node {
  ListenerNode(const rclcpp::NodeOptions & options)
  : Node("listener", options)
  {
    ...
  }
}
}  // namespace composition_example

• Must contain a registration macro and header in a single translation unit. For example, the following at the bottom of your cpp file would suffice:

// Insert at bottom of translation unit, e.g. listener_node.cpp
#include <rclcpp_components/register_node_macro.hpp>
// Use fully-qualified name in registration
RCLCPP_COMPONENTS_REGISTER_NODE(composition_example::ListenerNode)

• Must compile the components as a shared library and register them in your CMakeLists.txt file.
• Must depend on the rclcpp_components package.

Minimal CMake Example

The following is a minimal CMakeLists.txt file which uses the recommended ament_cmake_auto macros, registers a single component, builds a stand-alone node which uses the component, and exports it as a dependency for downstream packages. It can be conveniently created by autoware_auto_create_pkg:

cmake_minimum_required(VERSION 3.5)
project(composition_example)
 
# Default to C++14
if(NOT CMAKE_CXX_STANDARD)
  set(CMAKE_CXX_STANDARD 14)
endif()
 
if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
  add_compile_options(-Wall -Wextra -Wpedantic)
endif()
 
find_package(ament_cmake_auto REQUIRED)
ament_auto_find_build_dependencies()
 
ament_auto_add_library(listener_node SHARED src/listener_node.cpp)
autoware_set_compile_options(listener_node)
rclcpp_components_register_nodes(listener_node "composition_example::ListenerNode")
 
ament_auto_add_executable(listener_node_exe src/listener_main.cpp)
autoware_set_compile_options(listener_node_exe)
 
if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  ament_lint_auto_find_test_dependencies()
endif()
 
ament_auto_package()

Minimal Package.xml Example

The following is a minimal package.xml file to go with the above CMakeLists.txt example:

<?xml version="1.0"?>
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
  <name>composition_example</name>
  <version>0.0.1</version>
  <description>Example of node composition</description>
  <maintainer email="my.email@example.com">The Autoware Foundation</maintainer>
  <license>Apache License 2.0</license>
 
  <buildtool_depend>ament_cmake_auto</buildtool_depend>
  <buildtool_depend>autoware_auto_cmake</buildtool_depend>
 
  <depend>rclcpp</depend>
  <depend>rclcpp_components</depend>
 
  <test_depend>ament_lint_auto</test_depend>
  <test_depend>ament_lint_common</test_depend>
 
  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

Resources

• rclcpp_components in Dashing Diademata Release Notes