Releasing a ROS package

Assumptions: This wiki assumes you are using the new catkin tools. (No rosbuild and not the old catkin stack (catkin_make)!)

Your package is called example-package and is stored in a git repo of the my-example-org organisation.

Making sure the package is ready

Make sure that the package is running locally. Run catkin build to make sure the package builds at all. Now to make sure that the install command works too, run

catkin config --install
catkin clean -b
catkin build

This should create an install folder in your catkin workspace (usually ~/catkin_ws). Now source the according setup.* file in the install folder (* should be replaced by the script file type of your shell). Now run your commands just as you normally would.

If you get a message after running the first command that says:

----------------------------------------------------------
WARNING: Your workspace is not extending any other result
space, but it is set to use a `linked` devel space
layout. This requires the `catkin` CMake package in your
source space in order to be built.
----------------------------------------------------------

you may want to explicitly extend from a base ROS distro to ensure that your package builds, e.g.: catkin config --install --extend /opt/ros/noetic/

To make sure the installation worked run roscd example-package.This should get you somewhere similar to: catkin_ws/install/.../your-package. If there is no install in the path something went wrong and you should retry the previous step. If your package works the way it normally would and you can everything, step right ahead into Adding your package to the index.

If you are still struggling, here are a few hints: a) Make sure your Manifest is correct and you have not made any errors there.

b) Make sure the CMakeLists.txt is correct too. If no errors have shown up so far this is the place to look. Probably you forgotten to add install commands. In this case switch directly to step 10 there - it will provide you with the information on how add the executable files and scripts to catkin. All done? Let's run some prerelease test - oh wait.

Adding your package to the index

Why add a package to the index?

Now this next part is kind of confusing - before you can run prerelase tests you have to add the package to the index. You need to do so to make them publicly available and visible to the other developers. This step has to be repeated for every ROS distribution. Apart from technical reasons this process helps to make sure your package has been built and tested on that specific plattform.

Adding a package to rosdistro

So how do you add packages to the index? You fork the rosdistro repo and modify it accordingly. This Github document on forking may be helpful in the process.

@Andreas: Shall I add more info on forking here?

In this example we will only modify the distribution file of the kinetic version - kinetic/distribution.yml:

Search for the right place (alphabetically) to add your package, then do (adapt to your needs):

example-package:
    source:
         type: git
         url: https://github.com/my-example-org/example-package.git
         version: master
    status:maintained

Before you commit your changes make sure they match the ROS conventions by running rosdistro reformat distribution.yaml. This will fix any (formatting) errors so that you can commit and push your changes back to the main repo. Any changes that contain errors will be rejected by the maintainers.

Note that the updates of the global index may take time some time.

Futher information can be found here: Which repositories can be tested.

Running prerelease tests

Why prerelease tests?

Now imagine what happens if you have a depency not specified in the package.xml and try run it on your local machine? It will run but it won't on any other machine where this depedency is missing. This is one of the reasons for the Docker based prerelase tests. They will install your package in a clean environment. Apart from that the ususal package tests are executed too and thus a completed prerelease test is a quite good guarantee that the package will run perfectly on this platform.

Note that this is only true for build / install requirements. Run requirements are not necesarily checked if you did not add any tests that are actually running the program.

Prerelease tests requirements

Follow the instructions here: How do I setup my system to run a prerelease?

This helps you install all required packages for the prerelease to run correctly.

Running a prerelease test

To generate a prerelease script go to http://prerelease.ros.org/, choose the distribution you want to test on and your package. You could also add further package here if you want to test multiple packages on this run.

For your package to be found in this webpage it must be indexed in the according distribution.yml! If you have not done so, go back to Adding your package to the index.

The remaining part is straight format, just leave the defaults. In the end you have a paste of code you can just paste to your console. Do so and follow the instructions there.

Congrats, you just ran a prerelease test. Even better if no errors have been popping up. If they have, follow the instructions to reproduce which will be printed along the error messages. Fix those before continuing. What can I do when a prerelease fails may help you.

Further information: regression_tests

Releasing your package as a binary

You are all done and can finally release the package as a binary.

So far we made sure that a) the package installs correctly b) the package is added to the index c) made sure the package builds correctly and d) ran prerelease tests.

Why binary releases?

Wouldn't it be nice to just run apt-get install ros-rosdistro-example-package and the package will be installed? This heavily simplifies the deployment on many machines and also is a way of making sure that only good packages will be installed. Completely broken packages will fail on the build step.

The ROS tool for releasing binary packages is called bloom. You can either follow the instructions in this article or the simplified instructions provided here.

(optional) Generate a changelog

If you want to do so. Note that this may not be a trivial process especially if your commits include _ signs. Those are interpreted as links in the RST format and have to be escaped manually. More information here.

(optional) Update your package.xml

This is mostly needed to increase the version in all packages in this repo. Also this step adds tags to the repository so that you may go back to this version at any time. To do so call catkin_prepare_release in the repo. It will you guide through all necessary steps.

Create a release repository

Create a new repository in Github (in this case in the organization). By convention you should name it as your package name with the -release suffix. So for the example-package repository the corresponding release repository would be called example-package-release.

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.

More information: Creating a Release Repository

Releasing Your Packages

Normally you will make a call like this:

# This is for the first release
$ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name --edit
# on any further call you can remove the --edit as you no longer need to change the
# configuration. If  you want to add a new config you may have to readd the --edit parameter
$ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name

bloom-release will guide through all necessary steps including the upload of the releases to the corresponding repository. Apart from that it also modifies the entry in the distribution.yml to add the release information there. With this information added the binary packages will be built too. This step has to be repeated for all rosdistros you want to publish your package on.

@Andreas: Shall I add more information here?

If you want to learn more about the build infrastructure, read / listen to the talk from the ROSCon 2016 (pdf / video)

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.

You can check the status of your package in http://repositories.ros.org/status_page/ by following the according rosdistro link.

Open stuff:

Wofür werden die tracks gebraucht?

Gemeinsam bloom-release durchgehen und eventuell einfügen

add http://build.ros.org/