Releasing a new version of a catkin package

Contents

Releasing a new version of a catkin package

By default, bloom releases packages to the public ROS build farm. See build.ros.org for more information and for policies about released packages.

Prerequisites

This tutorial assumes that you, or someone else, has previously released this package by following the Releasing a Package for the First Time tutorial.

We recommend you do a pre-release before the real release.

Follow this tutorial for instructions: Running a pre-release test

Preparing the Upstream Repository

This page will walk you through setting up your repository for a Bloom release.

Note: This part of the release procedure will not work for ROS2 packages, since ROS2 uses a new build system. If using ROS2, you will have to create the changelog and release tags yourself. Please see the ROS 2 Bloom page for more information.

Update Changelogs

They are not mandatory but recommended (ref: REP-132).

Generate a Changelog

```
$ catkin_generate_changelog
```

Run catkin_generate_changelog to generate or update CHANGELOG.rst file(s). If one or more package(s) don't contain CHANGELOG.rst, add --all option to populate all the previous commits for each package.

Clean up the Changelog

The command catkin_generate_changelog will simply populate them with the commit logs which are not always appropriate for changelogs. Open CHANGELOG.rst and edit to your liking. NOTE: Do not modify the "Forthcoming" header label. It will be modified in the later step when running "catkin_prepare_release". Here is an example of a well formatted CHANGELOG.rst.

Don't forget to complete the next step!

Note: Incorrectly formatted CHANGELOG.rst can cause problems with your package.

Note: if you have any commit messages ending in an underscore, such as member variables (e.g. name_) this will throw an error with the RST Changelog format because RST treats those as link targets. The error will be something like:

<string>:21: (ERROR/3) Unknown target name: "name".

To fix this, you'll need to escape the variable, for example:

* fix for checking the ``name_``

Commit the Changelog

This step is important, don't forget it! Commit your new/updated changelog.

Note: Some additional information on catkin_generate_changelog, including some command line flags, can be found at the original discussion thread ( $/!\$ This reference should eventually be replaced by a more authoritative documentation, rather than an email discussion thread)

Update package.xml Version

You must bump the version in your package.xml file(s) and create a tag matching that version in your upstream repository. catkin provides a tool for doing this, and it is called catkin_prepare_release:

$ cd /path/to/your/upstream/repository
$ catkin_prepare_release

This command will find all of the packages in your upstream repository:

check that they have changelogs (and then they have no uncommitted local changes)
increment the version in your package.xml(s)
replaces the heading Forthcoming with "version (date)" (eg. 0.0.1 (2022-01-08)) in CHANGELOG.rst
commit/tag/push the changes with a bloom compatible flag

Using this command is the best way to ensure you have a consistent and recommended release of your package.

By default this command increases the patch version of your package, e.g. 0.1.1 -> 0.1.2, but you can pick minor or major using the --bump option.

Even if you do not use catkin_prepare_release, you must have one or more valid package.xml(s) with the same version and a matching tag in your upstream repository.

Release the catkin Package

Note: If you have two factor authorization enabled on github, please follow this tutorial first: GithubManualAuthorization

This part is easy, in any folder run:

```
$ bloom-release foo --rosdistro kinetic
```

Where foo is the name of your repository (name used in the ROS distro file) and kinetic is the name of the rosdistro you are releasing for. The "track" is set to be equivalent to the rosdistro unless otherwise specified.

This command will fetch your release repository, run git-bloom-release <track> on it, and then push your changes to your hosted release repository, ditching the fetched release repository afterwards, and finally opening a pull request on your behalf.

That's it.

$/!\$ If you took over from someone a pkg that's already been released and run bloom-release, you might see a situation like this. In that case ask for push access to that repository.

Note: If your repository contains more packages in subdirectories, the whole release process expects you update all of them in sync each time. I.e. catkin_generate_changelog and catkin_prepare_release traverse all packages in the repository and work on all of them, and bloom-release releases all of them. There is no way around the first two (but you can substitute them with manual steps). If you only want to bloom-release a subset of the packages as binary packages, you can create a file called <track>.ignored (i.e. melodic.ignored) in the root of the release repository (not the upstream repo) on branch master (this name is not configurable). In this file, you can list whitespace-separated packages that should not be released by bloom in this step. Example here, discussion 1, discussion 2.

Notifying the Build Farm

If the automated pull request did not work then you will need to manually open a pull request to notify the build farm that you have a new version of your packages to build.

For each ROS distribution there is a distro file hosted on Github, for kinetic it is:

https://github.com/ros/rosdistro/blob/master/kinetic/distribution.yaml

You can open a pull request on this file by simply visiting the above URL and clicking the edit button (note: you have to be logged into Github for this to work), make your changes and then click "Propose Changes" at the bottom right of the page.

To update your version, simply find your repository in the list and update the associated version. Note that you must put the full version which is the version of your package plus the release increment number separated by a hyphen. The release increment number is increased each time you release a package of the same version, this can occur when adding patches to the release repository or when changing the release settings.