Releasing a Package for the First Time

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

Please get started by installing bloom.

Before releasing your packages, you will need to prepare your upstream repository for release. The upstream repository is the repository where you do your development and host the source code of your package. This repository can be hosted anywhere (even locally) and can be a git, hg, or svn repository or the location of an archive (tar.gz only for now, but there are plans for tar.bz and zip).

If your upstream repository is a vcs (git, hg, or svn), then it must have a tag matching the version you intend to release. For example, if you are going to release version 0.1.0 of your package, then bloom expects there to be a 0.1.0 tag in your upstream repository. If you have a different version tagging scheme, then bloom can handle that using the 'Release Tag' configuration which you will see later in this tutorial while configuring a release track.

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

Generate

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

Cleanup

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

Commit

# Review, Edit and Commit your changes!

Reference:

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.

Next, let's talk about how bloom works. First, bloom requires that you have a separate "release" repository for releasing your package. This repository must be a git repository and is normally hosted. For example, all of the ROS release repositories are in the ros-gbp github organization. These repositories are the result of running bloom on a repository containing one or more catkin packages. We highly recommend that you host your release repository on https://github.com.

Creating a Release Repository

The next step is to create your release repository. This tutorial will cover creating of a repository on github.com but you can also create one locally and host it somewhere else.

Creating a Release Repository on github.com

Create a new repository in the github organization or on the github user of your choice. By convention you should name it as your package name with the -release suffix. So for the ros_comm repository the corresponding release repository is called ros_comm-release. Note: When creating your github.com repository, check the box Initialize this repository with a README.md, this way it starts out as a valid git repo. Bloom will later fill this file with information about released versions.

Once you have created this new release repository then you are ready to configure and release you package. Grab the release repository url from the github page, because you'll need it next.

Releasing Your Packages

Normally you will make a call like this:

  • # This is an example, do not run this one, run the next one
    $ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name

In order to release the packages from a repository, but on the first release (and any time you want to configure a new 'track' of settings) you'll want to add the --edit option:

  • # Replace <ros_distro> with the ROS distribution, e.g. indigo
    $ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name --edit

This option will allow you to edit the track specified before making a release. This is required on the first release as you do not yet have a track, so bloom will first create one for you and then allow you to configure it. Please note that repository_name is not its url, it is its reference in distribution.yaml.

When you run the above command, it will go out to the ROS distro file for the ROS distro which you specified and look for your repository's information. Since this is your first release, it will not find your repository's information, so it will ask you for the release repository url, like this:

No reasonable default release repository url could be determined from previous releases.
Release repository url [press enter to abort]: 

You will only have to provide this information on the first release, but put your RELEASE repository url here. This is the repository you just created above.

Next bloom may ask you about initializing the new repository.

Freshly initialized git repository detected.
An initial empty commit is going to be made.
Continue [Y/n]? 

Hit enter or type 'y' and then hit enter to continue.

Now bloom will setup a master branch (this is where the configurations are stored) and begin prompting you for information about the release.

Configure a Release Track

bloom is designed to allow the release of the same package for different ROS distributions and versions in the same release repository. To facilitate this, bloom uses release "tracks" to maintain configurations for different release processes. For normal catkin-based ROS packages the default release track is recommended.

In the bloom-release command you ran above, you specified the --track. By convention you should create tracks with the same name as the ROS distro you are releasing for, but you could name your track what ever you wanted.

The first question provided to you is the repository name:

Repository Name:
  upstream
    Default value, leave this as upstream if you are unsure
  <name>
    Name of the repository (used in the archive name)
  ['upstream']:

This name is trivial, but can be used to provide additional tags and to create nicer archive names. Since our example has a single package called foo in the repository, it would be appropriate to put foo here.

The next configuration is the upstream repository uri:

Upstream Repository URI:
  <uri>
    Any valid URI. This variable can be templated, for example an svn url
    can be templated as such: "https://svn.foo.com/foo/tags/foo-:{version}"
    where the :{version} token will be replaced with the version for this release.
  [None]:

This is an important setting; you should put the uri of your repository on which you do development. This is NOT the place where you intend to host this release repository. In this case, I will pretend that our code is hosted in the bar organization on github and put https://github.com/bar/foo.git.

Next, bloom will prompt you for the upstream repository type.

Upstream VCS Type:
  svn
    Upstream URI is a svn repository
  git
    Upstream URI is a git repository
  hg
    Upstream URI is a hg repository
  tar
    Upstream URI is a tarball
  ['git']: 

In this example our upstream repository is git, but svn, hg, and hosted tar archives are also supported.

The next few options (Version and Release Tag) should be okay to leave as the defaults and are rarely changed unless you are releasing a non-catkin package. Simply press enter to accept the default.

The next option you need to potentially modify is the upstream development branch:

Upstream Devel Branch:
  <vcs reference>
    Branch in upstream repository on which to search for the version.
    This is used only when version is set to ':{auto}'.
  [None]:

This option is the branch of your upstream repository from which you tag releases. If this is left None then the default branch is used when guessing the version being released. If you want to search a branch besides the default branch, choose that. For example, if you want to use the branch indigo-devel for this release track, enter indigo-devel.

Next the ROS distro is required:

ROS Distro:
  <ROS distro>
    This can be any valid ROS distro, e.g. groovy, hydro
  ['indigo']:

Enter the name of the ROS distro that this track is based on.

The rest of the configurations (Patches Directory, can be left as the default in most cases.

Congratulations, you have successfully configured your release track.

There are many command which come with bloom, even though you will most likely only need to run bloom-release. Many of the bloom commands are prefixed with git-, which indicates that they must be run inside a git repository. If you clone your release repository manually, then you can use git- prefixed commands to manually manipulate your release repository. One of these commands is called git-bloom-config and it lets you manage your tracks. Run git-bloom-config -h to get more information about how to manage your release tracks.

Finishing the Release

After your finished configuring your repository, bloom-release will do many things, but generally it is cloning your release repository, performing all of the release tasks defined in the actions section of your release track, pushing the result, and finally opening a pull request on your behalf. If you configured your release repository correctly then your bloom release should eventually succeed, after prompting you for you github credentials. Once it is done, then it should provide you with a link to the newly created pull request.

Notifying the Build Farm

Normally your bloom-release call should open a pull request for you, but if there is a problem or you do not wish for it to open the pull request on your behalf you can manually open a pull request also. If the automated pull request was opened successfully, then you do not need to open one manually as described below.

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

https://github.com/ros/rosdistro/blob/master/hydro/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 enter your repository you need to fill out a section like this:

repositories:
  ...
  foo:
    tags:
      release: release/groovy/{package}/{version}
    url: https://github.com/ros-gbp/foo-release.git
    version: 0.1.0-0
  ...

Make sure to use the correct ROS distro name in the release tag (groovy in this case).

Note that you should put the https:// url of the RELEASE repository here, not the url of your source repository. Also 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. Also note that you should put your package into the list of packages in ALPHABETICAL order. Please.

Note: If your repository contains multiple packages, their names must be listed in the distro file, too:

repositories:
  ...
  foo:
    packages:
      foo_msgs:
      foo_server:
      foo_utils:
    tags:
      release: release/groovy/{package}/{version}
    url: https://github.com/ros-gbp/foo-release.git
    version: 0.1.0-0
  ...

Again remember to use the correct ROS distro name for the release tag.

Note: each item in the list of packages must end with a colon. If necessary, a path to that package can be specified after the colon if it is not located in the repository root. For example:

    packages:
      foo_msgs: util/foo_msgs
      foo_server: tool/foo_server

Next Steps

Once your pull request has been submitted then you will have to wait for one of the ROS developers to merge your request (this usually happens fairly quickly). Then after 24-48 hours your package should be built by the build farm and released into the building repository. Packages built are periodically synchronized over to the shadow-fixed and public repositories, so it might take some time (weeks) before your package has made it into the public ROS debian repositories.

Wiki: bloom/Tutorials/FirstTimeRelease (last edited 2016-07-30 02:46:24 by IsaacSaito)