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. 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, 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.

Wiki: bloom/Tutorials/PrepareUpstream (last edited 2024-01-30 22:49:33 by TullyFoote)