From 0eaff35ae24e6abb18b4210267d0ff891ea0fd72 Mon Sep 17 00:00:00 2001 From: Max SCHMELLER Date: Tue, 7 Apr 2026 19:50:32 +0900 Subject: [PATCH 1/2] docs: add release guide to documentation Signed-off-by: Max SCHMELLER --- docs/contributing/cutting_releases.md | 56 +++++++++++++++++++++++++++ zensical.toml | 1 + 2 files changed, 57 insertions(+) create mode 100644 docs/contributing/cutting_releases.md diff --git a/docs/contributing/cutting_releases.md b/docs/contributing/cutting_releases.md new file mode 100644 index 000000000..e89d94465 --- /dev/null +++ b/docs/contributing/cutting_releases.md @@ -0,0 +1,56 @@ +--- +icon: lucide/rocket +--- + +# Cutting Releases + +Release rules at one glance: + +* Releases are always cut from the `main` branch. +* Nebula follows [Semantic Versioning](https://semver.org/). +* Version tags are prefixed with `v`, e.g. `v1.2.3`. +* Nebula uses [Bloom and Catkin](https://docs.ros.org/en/humble/How-To-Guides/Releasing/Releasing-a-Package.html) + to manage releases and changelogs. +* Releases and tags are never deleted or modified after creation. If a mistake is made, a new + release should be created to fix it. + +## Release Process + +The below steps have to be followed strictly for every release: + +1. Ensure all changes for the release are merged into `main`. +2. Follow the [Subsequent Releases](https://docs.ros.org/en/humble/How-To-Guides/Releasing/Subsequent-Releases.html) + guide to update the changelog, bump the version, and create pull requests to rosdistro. + 1. Update changelogs using `catkin_generate_changelog`, then PR and merge to `main`. + 2. Bump the version using `catkin_prepare_release` directly on `main`. + 3. Notify the ROS 2 ecosystem using `bloom-release`. Do this once per supported ROS 2 distribution, + e.g. `bloom-release --rosdistro humble nebula`, then `bloom-release --rosdistro jazzy nebula`. +3. Create a new GitHub release on the [GitHub Releases](https://github.com/tier4/nebula/releases/new) + page, using the already created tag from step 2. + +!!! warning "Check for breaking changes" + As per the semantic versioning rules, the major/minor/patch version should be bumped based + on the type of changes in the release. Familiarize with [Semantic Versioning](https://semver.org/), + and ensure to bump the version correctly in accordance with the changes in the release. + +## ROS 2 Releases + +The above steps already cover the process for cutting ROS 2 releases, and these will +automatically be published as ROS 2 packages after some time. On the ROS side, the process looks +as follows: + +1. You `bloom-release` a new version of the package. + 1. Bloom updates the [Nebula Release Repository](https://github.com/ros2-gbp/nebula-release) + 2. Bloom creates a pull request to [ros2/rosdistro](https://github.com/ros/rosdistro), e.g. + [ros/rosdistro#50573](https://github.com/ros/rosdistro/pull/50573) +2. A rosdistro maintainer reviews and merges the pull request. +3. New packages appear in Rosdep, i.e. in `rosdep update && rosdep resolve my_new_package`. +4. The [ROS 2 buildfarm](https://build.ros2.org/) builds the new packages. +5. A ROS 2 [distro sync](https://discourse.openrobotics.org/tag/sync/117/l/latest) publishes + the new packages to APT. + +!!! warning "Rosdep-APT Time Delay" + A package visible to Rosdep does not appear in APT until a ROS 2 distro sync happens, which + is usually every 1-2 months. This means there is a significant time delay from cutting a + release to users being able to install it via APT. + Time-sensitive users should add Nebula to their `build_depends.repos` and do a source build. diff --git a/zensical.toml b/zensical.toml index 1040cc5c2..315193827 100644 --- a/zensical.toml +++ b/zensical.toml @@ -55,6 +55,7 @@ nav = [ { "Contributing to Nebula" = "contributing/index.md" }, { "Integration Guide" = "integration_guide.md" }, { "Benchmarking" = "contributing/benchmarking.md" }, + { "Cutting Releases" = "contributing/cutting_releases.md" }, ] }, { "API Reference" = [ { "API Reference" = "api_reference.md" }, From 0647e982a2adb8e55874c0c88c797f904f11dc7f Mon Sep 17 00:00:00 2001 From: Max SCHMELLER Date: Tue, 7 Apr 2026 22:25:20 +0900 Subject: [PATCH 2/2] docs: ignore prettier Signed-off-by: Max SCHMELLER --- docs/contributing/cutting_releases.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/contributing/cutting_releases.md b/docs/contributing/cutting_releases.md index e89d94465..7f578835f 100644 --- a/docs/contributing/cutting_releases.md +++ b/docs/contributing/cutting_releases.md @@ -2,6 +2,8 @@ icon: lucide/rocket --- + + # Cutting Releases Release rules at one glance: @@ -54,3 +56,5 @@ as follows: is usually every 1-2 months. This means there is a significant time delay from cutting a release to users being able to install it via APT. Time-sensitive users should add Nebula to their `build_depends.repos` and do a source build. + +