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 ( ![/!\](/moin_static197/rostheme/img/alert.png "/!\"){kind=small}
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.
