= Releasing a ROS package = <> {{{#!wiki caution This page looks to be duplicating content also found in: [[http://wiki.ros.org/rosdistro/Tutorials/Indexing%20Your%20ROS%20Repository%20for%20Documentation%20Generation|Indexing Your ROS Repository for Documentation Generation]] and [[http://wiki.ros.org/bloom/Tutorials/FirstTimeRelease|bloom/Releasing a Package for the First Time]] Content here should be merged into those two pages. }}} 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 [[https://catkin-tools.readthedocs.io/en/latest/verbs/catkin_config.html#explicitly-specifying-workspace-chaining|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|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 [[rosbuild/CMakeLists|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 [[catkin/CMakeLists.txt#Optional_Step:_Specifying_Installable_Targets|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 [[Distributions|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 [[https://github.com/ros/rosdistro|rosdistro repo]] and modify it accordingly. [[https://help.github.com/articles/syncing-a-fork/|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 - [[https://github.com/ros/rosdistro/blob/master/kinetic/distribution.yaml|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: [[http://wiki.ros.org/regression_tests#Which_repositories_can_be_tested.3F|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: [[regression_tests#How_do_I_setup_my_system_to_run_a_prerelease.3F|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|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. [[regression_tests#What_can_I_do_when_a_prerelease_fails.3F|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 [[bloom/Tutorials/FirstTimeRelease|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. [[bloom/Tutorials/FirstTimeRelease#bloom.2BAC8-Tutorials.2BAC8-PrepareUpstream.Update_Changelogs|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 [[Tutorials/FirstTimeRelease#bloom.2BAC8-Tutorials.2BAC8-PrepareUpstream.Update_package.xml_Version|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: [[bloom/Tutorials/FirstTimeRelease#Creating_a_Release_Repository|Creating a Release Repository]] === Releasing Your Packages === Normally you will make a call like this: {{{ # This is for the first release $ bloom-release --rosdistro --track 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 --track repository_name }}} `bloom-release` will guide through [[bloom/Tutorials/FirstTimeRelease#Releasing_Your_Packages|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 ([[http://roscon.ros.org/2016/presentations/ROSCon2016%20Build%20Farm.pdf|pdf]] / [[https://vimeo.com/187705230|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 [[http://wiki.ros.org/ShadowRepository|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: == [[http://answers.ros.org/question/252077/what-is-the-track-in-bloom-release-needed-for/|Wofür werden die tracks gebraucht?]] Gemeinsam bloom-release durchgehen und eventuell einfügen add http://build.ros.org/