Releasing a new version of a catkin package

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


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

Update Changelogs

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


  • $ 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.


Make sure to read and cleanup the changelogs. The command catkin_generate_changelog will simply populate them with the commit logs which are not always appropriate for changelogs.

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_``


# Review, Edit and Commit your changes!


If you decide to have one or more CHANGELOG.rst files, running these two commands is important; Incorrectly formatted CHANGELOG.rst can cause problems with your package. Remember to explicitly commit the changes to the Changelog!!

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, and commit/tag 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

This part is easy, in any folder run:

  • $ bloom-release foo --track kinetic --rosdistro kinetic

Where foo is the name of your repository (name used in the ROS distro file) and kinetic is both the name of your release track you want to run and the rosdistro you are releasing for, separated by options.

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.

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:

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.

Wiki: bloom/Tutorials/ReleaseCatkinPackage (last edited 2017-11-09 15:24:27 by TonyBaltovski)