diff --git a/get_started.md b/get_started.md index 80946c8108..9de0c0540b 100644 --- a/get_started.md +++ b/get_started.md @@ -32,6 +32,11 @@ installation options: * [Gazebo Harmonic (LTS) installation](/docs/harmonic/install){.external} options (EOL 2028 Sep) * [Gazebo Fortress (LTS) installation](/docs/fortress/install){.external} options (EOL 2026 Sep) +If you want to test the latest, unreleased Gazebo changes from `main`, see +the [Rotary release](releasing/rotary.md) documentation. Rotary is a +rolling release intended for maintainers and early adopters; new users +should stick to one of the binary releases above. + ## Step 2: Run After installing Gazebo in Step 1, you can launch Gazebo Sim, a 3D robotics diff --git a/release.md b/release.md index 9d66bcd3e3..d61ce0cda4 100644 --- a/release.md +++ b/release.md @@ -84,6 +84,15 @@ stability of the software: (see [the homebrew-simulation issue](https://github.com/osrf/homebrew-simulation/issues/1314) for more information). +:::{note} +**Rotary**: a rolling release stream built continuously from the `main` +branches of every Gazebo library, not tied to any codename or major +version. Rotary binaries are published into the same nightly apt +repository listed above and are available on macOS via Homebrew. See +the [Rotary release](releasing/rotary.md) page for an explanation of +the package naming rules and installation steps. +::: + ### Metadata for Releasing All package managers need to define different data fields in order to provide @@ -238,5 +247,6 @@ It is customary to use nightly binaries for all unreleased package versions. :maxdepth: 1 :titlesonly: +releasing/rotary releasing/versioning_pre_nightly ``` diff --git a/releases.md b/releases.md index c2494aec18..1bbbe2c5a0 100644 --- a/releases.md +++ b/releases.md @@ -10,10 +10,21 @@ A release of Gazebo consists of a set of versioned [Gazebo Libraries](/libs){.ex A Gazebo release follows the form "Gazebo Codename", for example Gazebo Acropolis. The codename is alphabetically increasing, and chosen to fall loosely within the architectural domain. +## Rolling releases + +Separate from the dated codename releases listed below, Gazebo also +publishes a rolling release stream called **Rotary**, built continuously +from the `main` branches of every Gazebo library every night. +Rotary is not tied to codename or major version and is intended for +maintainers, CI systems, and early adopters. +See the [Rotary release](releasing/rotary.md) page for details and +installation instructions. + ## Release List -| Name | Date | EOL date | Notes | -|----------------------------------------------------------|-----------|-----------|-------| +| Name | Date | EOL date | Notes | +|----------------------------------------------------------|-----------|-----------|--------------| +| [Rotary](releasing/rotary.md) | Rolling | — | Experimental | | M | Mar, 2027 | Nov, 2028 | | | [Jetty](https://gazebosim.org/docs/jetty) | Sep, 2025 | Sep, 2030 | LTS | | [Ionic](https://gazebosim.org/docs/ionic) | Sep, 2024 | Sep, 2026 | | diff --git a/releasing/rotary.md b/releasing/rotary.md new file mode 100644 index 0000000000..ed743e3dcf --- /dev/null +++ b/releasing/rotary.md @@ -0,0 +1,129 @@ +# Rotary release + +**Rotary** is a rolling release stream of Gazebo built continuously from the +`main` branches of every Gazebo library. Unlike the dated codename releases +(Fortress, Harmonic, Jetty, …), rotary has no fixed version: it is built +every night. It is intended for Gazebo maintainers, continuous +integration systems, and early adopters who want to test unreleased +changes before they ship in a named collection. + +:::{warning} +Rotary is a rolling, unstable stream. Breakage is expected, and versions +may change under you on every `apt upgrade` or `brew upgrade`. Rotary is +**not recommended for production use**. New Gazebo users should install +one of the binary releases listed in [Releases](../releases.md) instead. +::: + +## Package naming + +Wherever a Gazebo package name contains `gz-`, a `rotary-` infix is +injected to produce the rotary alias. The aliases point to unversioned +upstream packages, so installing a rotary alias always pulls whatever is +currently being built from `main`. + +### Ubuntu + + +| Regular package | Rotary alias | +|------------------------|---------------------------------| +| `libgz-cmake-dev` | `libgz-rotary-cmake-dev` | +| `gz-plugin-cli` | `gz-rotary-plugin-cli` | +| `python3-gz-math` | `python3-gz-rotary-math` | +| `libsdformat-dev` (*) | `libgz-rotary-sdformat-dev` | + +(*) sdformat is a special case: its package names do not contain `gz-`, +so the rotary alias adds a `gz-rotary-` prefix. + +### Homebrew (macOS) + +| Regular formula | Rotary alias | +|-----------------|---------------------| +| `gz-mathN` | `gz-rotary-math` | +| `sdformatN` | `gz-rotary-sdformat`| + + +### Umbrella metapackage + +On both Ubuntu and Homebrew, the `gz-rotary` metapackage pulls in the full +set of rotary libraries, mirroring how `gz-jetty` or `gz-harmonic` work for +named collections. + +## Installing Rotary on Ubuntu + +:::{note} +Rotary binaries are published into the existing **nightly** apt repository +at `http://packages.osrfoundation.org/gazebo/ubuntu-nightly`, so +the versioning scheme documented in +[Ubuntu versioning in nightly and prerelease binaries](versioning_pre_nightly.md) +applies to rotary unchanged. +::: + +First install the prerequisite tools: + +```bash +sudo apt-get update +sudo apt-get install curl lsb-release gnupg +``` + +Add the OSRF GPG key and configure the **nightly** apt repository (which +hosts rotary packages): + +```bash +sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-nightly $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-nightly.list > /dev/null +sudo apt-get update +``` + +Then install the Rotary metapackage: + +```bash +sudo apt-get install gz-rotary +``` + +All Rotary libraries should be ready to use and the `gz sim` app ready to +run. + +### Uninstalling rotary + +```bash +sudo apt remove gz-rotary && sudo apt autoremove +``` + +## Installing rotary on macOS (Homebrew) + +Rotary formulae are published through the +[`osrf/simulation`](https://github.com/osrf/homebrew-simulation) tap: + +```bash +brew tap osrf/simulation +brew install gz-rotary +``` + +Per-library formulae are also available using the `gz-rotary-` +naming scheme, for example: + +```bash +brew install gz-rotary-math gz-rotary-sim +``` + +The initial rollout of rotary brew formulae is tracked in +[osrf/homebrew-simulation#3287](https://github.com/osrf/homebrew-simulation/pull/3287). + +## Windows + +There is currently no binary distribution of rotary on Windows. Windows +users who want to run rotary need to build it from source. + +The existing [Source Installation on Windows 10 or 11](../install_windows_src.md) +guide for Jetty describes the full toolchain (Visual Studio, Pixi, +`colcon`). The same procedure applies to Rotary — the only change is +the `vcs import` step, which must point at `collection-rotary.yaml` from +[gazebo-tooling/gazebodistro](https://github.com/gazebo-tooling/gazebodistro) +instead of the Jetty collection file: + +```bash +vcs import --input https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-rotary.yaml src/ +``` + +After the import, continue with the "Building the Gazebo Libraries" step +of the Jetty Windows source guide unchanged.