Warning

You're reading the documentation for a version of ROS 2 that has reached its EOL (end-of-life), and is no longer officially supported. If you want up-to-date information, please have a look at Jazzy.

First Time Release

This guide explains how to release ROS 2 packages that you have not released before. Due to numerous options available when releasing ROS packages, this guide intends to cover the most common scenario and does not cover every corner-case.

Be part of a release team

You must be part of a release team. If you are not part of a release team yet, follow either:

Create a new release repository

You need a release repository to release a package. Follow Create a new release repository.

Install dependencies

Install tools that you will use in the upcoming steps according to your platform:

sudo apt install python3-bloom python3-catkin-pkg

Make sure you have rosdep initialized:

sudo rosdep init
rosdep update

Note that the rosdep init command may fail if it has already been initialized in the past; this can safely be ignored.

Set Up a Personal Access Token

Warning

If the file ~/.config/bloom exists on your computer, it is likely that you have done this before so you should skip this section.

During the release process, multiple HTTPS Git operations will be performed that require password authentication. To avoid being repeatedly asked for a password, a Personal Access Token (PAT) will be set up. If you have multi-factor authentication setup on your GitHub account, you must setup a Personal Access Token.

Create a Personal Access Token by:

  1. Log in to GitHub and go to Personal access tokens.

  2. Click the Generate new token button.

  3. In the dropdown, select Generate new token (classic)

  4. Set Note to something like Bloom token.

  5. Set Expiration to No expiration.

  6. Tick the public_repo and workflow checkboxes.

  7. Click the Generate token button.

After you have created the token, you will end up back at the Personal access tokens page. Copy the alphanumeric token that is highlighted in green.

Save your GitHub username and PAT to a new file called ~/.config/bloom, with the format below:

{
   "github_user": "<your-github-username>",
   "oauth_token": "<token-you-created-for-bloom>"
}

Ensure repositories are up-to-date

Make sure that:

  • Your repository is hosted on a remote such as GitHub.

  • You have a clone of the repository on your computer and are on the right branch.

  • Both the remote repository and your clone are up-to-date.

Generate Changelog

Generate a CHANGELOG.rst file per package in your repo using the following command:

catkin_generate_changelog --all

Open all CHANGELOG.rst files in an editor. You will see that catkin_generate_changelog has auto-generated a forthcoming section with notes from commit messages:

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Changelog for package your_package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Forthcoming
-----------
* you can modify this commit message
* and this

Clean up the list of commit messages to concisely convey the notable changes that have been made to the packages since the last release, and commit all the CHANGELOG.rst files. Do not modify the Forthcoming header.

Bump the package version

Every release of the package must have a unique version number higher than the previous release. Run:

catkin_prepare_release

which performs the following:

  1. increases the package version in package.xml

  2. replaces the heading Forthcoming with version (date) (eg. 0.0.1 (2022-01-08)) in CHANGELOG.rst

  3. commits those changes

  4. creates a tag (eg. 0.0.1)

  5. pushes the changes and the tag to your remote repository

Note

By default the patch version of the package is incremented, such as from 0.0.0 to 0.0.1. To increment the minor or major version instead, run catkin_prepare_release --bump minor or catkin_prepare_release --bump major. For more details, see catkin_prepare_release --help.

Bloom Release

Run the following command, replacing my_repo with the name of your repository:

bloom-release --new-track --rosdistro iron --track iron my_repo

Tip

  • --new-track tells bloom to create a new track and configure it.

  • --rosdistro iron indicates that this release is for the iron distro

  • --track iron indicates that you want the track name to be iron

You will be prompted to enter information to configure a new track. In a common scenario such as:

  • Your packages are in a repository called my_repo

  • You are releasing a branch called main

  • The repository is hosted on GitHub at https://github.com/my_organization/my_repo.git

  • Your release repository is at https://github.com/ros2-gbp/my_repo-release.git

You should respond to the prompts as following:

Configuration

Value

Release Repository url

https://github.com/ros2-gbp/my_repo-release.git

Repository Name

my_repo

Upstream Repository URI

https://github.com/my_organization/my_repo.git

Upstream VCS Type

Version

Release Tag

Upstream Devel Branch

main

ROS Distro

Patches Directory

Release Repository Push URL

Note

An empty cell in the table indicates that the default value should be used. Simply respond to the prompt by pressing Enter.

Bloom will automatically create a pull request for you against rosdistro.

Next Steps

Once your pull request has been submitted, usually within one or two days, one of the maintainers of rosdistro will review and merge your Pull Request. If your package build is successful, in 24-48 hours your packages will become available in the ros-testing repository, where you can test your pre-release binaries.

Approximately every two to four weeks, the distribution’s release manager manually synchronizes the contents of ros-testing into the main ROS repository. This is when your packages actually become available to the rest of the ROS community. To get updates on when the next synchronization (sync) is coming, subscribe to the Packaging and Release Management Category on ROS Discourse.