At Team Spatzenhirn, the Carolo-Cup (1:10 scale autonomous driving competition) team at Ulm University, we use ROS 2 for our autonomous-driving software stack.

ROS allows researchers and robotics enthusiasts to share software in a common format, which simplifies reuse by others. The core concept of this is a ROS package, which may be released using the ROS infrastructure, allowing it to be included in future ROS releases and installed by others in binary form using the system package manager.

The package we want to release is rviz_2d_overlay_plugins, a fork and ROS 2 port of (parts of) the jsk_visualization package, which provides the functionality of 2D overlays in the standard visualization tool RViz, which is part of ROS.

The process of releasing a package is described in the official docs, but this should serve as a report of the process from the view of a first time contributor.

Preparations, Permissions, Repositories⌗

Making releases to a ROS package requires a release repository, and most of the release repositories of ROS packages are contained in the ros2-gbp GitHub organization. To allow package maintainers access to the proper release repos, a team in the GitHub organization is created.

Requesting a new team and release repo is done by creating an issue in the ros2-gbp-github-org repo, here is the issue to create our team. Make sure the package.xml of your package lists the maintainers you want to give access to the release repo to, as the issue template wants you to link the proper line in the package manifest!

In this issue we were made aware of a recent, not yet documented, step in the process: Registering the repository (not containing any released packages at that point) in the distribution file in the rosdistro repository. This is for the purpose of undergoing an early license and naming review, which in our case indeed uncovered a potential issue with the name of our package, prompting us to rename the package before release. The process can be followed in our first rosdistro PR as well as the second rosdistro PR with a fixed package name, that got merged without any further problems!

Finally, the teamspatzenhirn release team and our release repo got created, via this PR!

At this point, we already received the first emails from the ROS buildfarm which automatically runs CI on the repo!

Hello Friend
The email from the ROS buildfarm

It even discovered some third-party packages we depended on, but forgot to declare in our package.xml.

Hello Friend
The cmake issue, which was resolved by declaring the dependency in package.xml

Release!⌗

The first part of the release process is to update the changelog, bump all version numbers and push a git tag for the version. This is automated using the catkin_generate_changelog and catkin_prepare_release tools, and happens all within the package repository. This means that this step can absolutely be done before the release repo is set up, and we did tag multiple release versions, while waiting for the reviews above.

The second part is actually generating all the configuration for building binary releases in the release repo, and registering those releases in the rosdistro repo. All of this is automated using bloom-release, which is an interactive tool that on the first run requires the user to enter the package and release repo url, branch and some other configuration. One very useful prompt, which I did not fully understand on the first run is the Release Repository Push URL: This allows using the SSH url to push to the release repo, the earlier prompt for the release URL requires the HTTP version. The interactive user interface and the option to cancel (and restart) at any time made this not too difficult.

One issue discovered with bloom is that it refuses to push to the completely empty release repository on the first run. This is however a known issue, and the easy workaround is to create an (empty) README.md on the master branch of the release repo.

Bloom created all the branches and data found in our release repo, as well as the pull request to release into rolling, and to release into humble after running it again with --rosdistro humble.

At the time of writing, the rolling PR is merged and a sync is in progress, meaning the rviz_2d_overlay_plugins package should be available via apt install ... in the next few days, for those on ROS 2 rolling. The humble PR is currently on hold due to an ongoing sync, but should be included in the next one. The current release status is always visible on the ROS Index page.

CI, Documentation Generation⌗

Releasing a ROS package does not only make it easier for others to install the package. It also provides the package maintainers with a few services, such as CI builds for the main branch via the ROS buildfarm, CI for merge requests, and generating and hosting documentation for the package. The documentation for these services is hard to find, if it even exists… We learned of the main branch CI by receiving a mail about the failed build, a key for enabling the PR CI exists in the rosdistro repo (we will see what happens, once the humble release is done…), and we were encouraged to enable documentation generation there as well. I found the tool generating the documentation, rosdoc2, and might provide a more detailed writeup on configuring that, once I figure that out myself…