ROS 2 contribution guide

Thank you in advance for contributing to gazebo_ros_pkgs! This guide has some guidelines to help contributors interested in porting Gazebo-ROS code from ROS 1 to ROS 2, as well as contributing new features to the ROS 2 implementation.

Note that this is a guide for contributors - for a guide on how to migrate to use gazebo_ros_pkgs with ROS 2, see the specific guide in the wiki.

These guidelines are meant to make sure that:

• The plugins are working as expected
• The code can be maintained for a longer time (by reducing duplication, standardizing style, having tests)
• Plugins can be easily tested both by newcomers and by experienced users

Guidelines

General contributions

These apply to porting ROS 1 code, as well as contributing new code.

High level

• Target the latest released branch which the change can be backported to without breaking API, ABI or behaviour. Breaking changes should target the ros2 branch. For example:
  • Add a new publisher to an existing plugin, using features available on Dashing upstream: target dashing
  • Change the definition of a message in gazebo_msgs: target ros2

In the code

• Follow ROS 2's style guidelines.
• Use the PIMPL pattern, see for example how the GazeboRosTemplate plugin has a GazeboRosTemplatePrivate class.
• Avoid using boost, migrate to std types whenever possible, such as std::mutex, std::bind, std::shared_ptr... Boost should only be used when it can't be avoided, like when it comes from Gazebo's API.
• Use the new conversion functions instead of manually converting types.
• Use nullptr instead of NULL
• Use terms that match Gazebo and SDF concepts, i.e.:
  • API that refers to links should use the word "link" instead of "body"
  • API that works for any entity, such as models and lights, should use "entity" instead of "model"

Testing

• Make sure all tests and linters pass, by running colcon test
• Add a basic test for the plugin. You should be able to start from one of the tests for plugins already ported.

Documentation

• Document all functions and member variables, even if they're not documented in ROS 1.
• Add usage documentation to the header, see the other plugins for examples.
• Add a demo world with instructions similar to the ones here.

Porting from ROS 1

Do all of the above, plus the following.

High level

• Delete the old files / parts of files from .ros1_unported

In the code

• Remove all ifdefs for GAZEBO_MAJOR_VERSION for Gazebo 8 and below.
• Use gazebo_ros::Node instead of rclcpp::Node, and pass it the sdf::ElementPtr as shown in this example.
• Double-check if all member variables are actually being used, and need to be held as member variables.
• Remove <robotNamespace> tags. Instead, use <ros><namespace>.
• Remove any SDF tags to set topic names, such as <odomTopic>. Instead, use remapping rules like <ros><argument>odom:=custom_odom</argument></ros>.
• Remove tf_prefix usage, since it is deprecated.
• Remove <updateRate> tags from sensors, since that can be set directly in the sensor.
• <gaussianNoise>:
  • In sensors: Remove tags and use noise from SDFormat and gazebo::sensors instead.
  • Elsewhere: Use Ignition Math's Random number generator.
• When porting messages and services, remove status_message fields, which would be better suited for console logging.

Documentation

• Add a migration guide for downstream users to the wiki.