bloom/Tutorials/PrepareUpstream

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.