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
package, which provides the functionality of 2D overlays in the standard visualization tool RViz, which is part of
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!
At this point, we already received the first emails from the ROS buildfarm which automatically runs CI on the repo!
It even discovered some third-party packages we depended on, but forgot to declare in our
The first part of the release process is to update the changelog, bump all version numbers and push a git tag for the
This is automated using the
catkin_prepare_release tools, and happens all within the
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
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.
At the time of writing, the rolling PR is merged and a sync is in progress, meaning the
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…