|
| 1 | +# Gazebo Release Instructions |
| 2 | + |
| 3 | +The following picture shows the interactions triggered when using the release |
| 4 | +tool [`release.py`](https://github.com/gazebo-tooling/release-tools/blob/master/release.py) explained in this guide: |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +Actions for releasing a new version of library (note that it can starts with |
| 9 | +ign or gz, ign/gz is used for this propose) `foo` with major version `X`: |
| 10 | + |
| 11 | + 1. [`release.py`](https://github.com/gazebo-tooling/release-tools/blob/master/release.py) |
| 12 | + will generate a local tarball with the source code of the new version and |
| 13 | + upload it to `osrf-distributions S3`. |
| 14 | + 1. `release.py` will start the following jobs in the build server |
| 15 | + `build.osrfoundation.org`: |
| 16 | + 1. `ign/gz-fooX-debbuilder`: multiple calls for different Debian/Ubuntu releases |
| 17 | + 1. [`generic-release-homebrew_pull_request_updater`](https://build.osrfoundation.org/job/generic-release-homebrew_pull_request_updater/): |
| 18 | + one call for Homebrew macOS release |
| 19 | + 1. `build.osrfoundation.org` jobs start the work of creating releases: |
| 20 | + 1. `ign/gz-fooX-debbuilder`: use tarball with release sources and metadata from `ign/gz-fooX-release` |
| 21 | + 1. `generic-release-homebrew_pull_request_updater`: use |
| 22 | + [`homebrew-simulation`](https://github.com/osrf/homebrew-simulation/) |
| 23 | + repository metadata together with the release sources |
| 24 | + 1. The output of the first round of initial jobs triggered by `release.py` is |
| 25 | + different: |
| 26 | + 1. `ign/gz-fooX-debbuilder`: builds the Debian/Ubuntu .deb packages and |
| 27 | + passes them to the `repository_uploader_packages` job |
| 28 | + 1. `generic-release-homebrew_pull_request_updater`: opens a |
| 29 | + new PR to coordinate the release process in `homebrew-simulation` |
| 30 | + 1. [`repository_uploader_packages`](https://build.osrfoundation.org/job/repository_uploader_packages/) |
| 31 | + imports the packages created by the `ign/gz-fooX-debbuilder` job (there will be |
| 32 | + one build for each platform combination of Ubuntu/Debian release |
| 33 | + and architecture) and uploads the .deb packages to |
| 34 | + `packages.osrfoundation.org` and [`osrf-distributions S3`](http://gazebosim.org/distributions). |
| 35 | + 1. For macOS, the PR in `homebrew-simulation` waits for a comment from an |
| 36 | + Gz developer with the order `build bottle` that will trigger the job |
| 37 | + [`generic-release-homebrew_triggered_bottle_builder`](https://build.osrfoundation.org/job/generic-release-homebrew_bottle_builder/). |
| 38 | + 1. `generic-release-homebrew_triggered_bottle_builder`will use the tarball with |
| 39 | + release sources from `osrf-distributions S3` to generate the binary bottles. |
| 40 | + They will be uploaded to `osrf-distributions S3`. |
| 41 | + |
| 42 | +## Initial setup |
| 43 | + |
| 44 | +A small number of configurations and credentials need to be made on the |
| 45 | +developer's system before triggering the release. If a permanent operating |
| 46 | +system is used for releasing, these installation steps only need to be |
| 47 | +executed once. |
| 48 | + |
| 49 | +### Software and configurations |
| 50 | + |
| 51 | +> Triggering the releasing process is only supported on Linux at this moment. |
| 52 | +
|
| 53 | +The tool designed to facilitate the process of releasing software for all |
| 54 | +platforms is called [`release.py`](https://github.com/gazebo-tooling/release-tools/blob/master/release.py), and is hosted at https://github.com/gazebo-tooling/release-tools. |
| 55 | +Cloning the `release-tools` repository is required to perform a new release: |
| 56 | + |
| 57 | +``` |
| 58 | +cd ~/ |
| 59 | +git clone https://github.com/gazebo-tooling/release-tools.git |
| 60 | +``` |
| 61 | + |
| 62 | +The `release.py` tool will use `sc3md` software to interact with Amazon AWS |
| 63 | +storage to host sources and binaries, so make sure `sc3md` is installed: |
| 64 | + |
| 65 | +``` |
| 66 | +sudo apt-get install s3cmd |
| 67 | +``` |
| 68 | + |
| 69 | +Some Debian tools require the following variables to be set: |
| 70 | +```bash |
| 71 | +export DEBEMAIL="<username>@openrobotics.org" |
| 72 | +export DEBFULLNAME="<Your full name>" |
| 73 | +``` |
| 74 | + |
| 75 | +> **Note:** the two above exported variables can be added to `.bashrc` to have |
| 76 | +> them configured automatically on every run. |
| 77 | +
|
| 78 | +### Access and Credentials |
| 79 | + |
| 80 | +Before starting the release process, make sure to ask for write access to: |
| 81 | +1. The Gz library intended to be released and |
| 82 | +2. `gazebo-release` repository. |
| 83 | + |
| 84 | +There are some credentials needed to interact with the release |
| 85 | +process: |
| 86 | + |
| 87 | + * S3 access to Open Robotics: |
| 88 | + ``` |
| 89 | + s3cmd --configure |
| 90 | + ``` |
| 91 | + If you don't have AWS credentials, please contact @j-rivero or @nuclearsandwich who will help set you up. |
| 92 | + |
| 93 | + * Release token: magic sequence of characters needed while running `release.py` |
| 94 | + to interact with `build.osrfoundation.org`. This should be given to Gz releasers as a part of the AWS credentials set-up. |
| 95 | + |
| 96 | +## For Each Release |
| 97 | + |
| 98 | +### Team and development checks |
| 99 | + |
| 100 | +When creating a new release, there are some guidelines to follow before starting |
| 101 | +the process: |
| 102 | + |
| 103 | + * Ask the team if there are any concerns about making the release. |
| 104 | + * Check if there are changes to previous library versions that need to be forward-ported. |
| 105 | + * See if there are open PRs against the release branch (release branch is the |
| 106 | + one with the name `ign/gz-fooX` where foo is the name of the Gz library and |
| 107 | + X the major version of the version bump planned) that could go into the new |
| 108 | + release. |
| 109 | + |
| 110 | +### Update code version and changelogs |
| 111 | + |
| 112 | +The first step to get a new release ready is to update the current code (upstream) |
| 113 | +version (view the [versioning](#versioning) section for more information). This |
| 114 | +bump could be in the major number (non-compatible changes), minor number (new |
| 115 | +features), patch number (patches and bugfixes). |
| 116 | + |
| 117 | +**Bumping major number** of the version implies some work to have the |
| 118 | +[metadata](#metadata-for-releasing) updated correctly. There is a [dedicated |
| 119 | +document](releasing/bump_major.md) that you should go through before continuing to work through the steps in this |
| 120 | +document. |
| 121 | + |
| 122 | + 1. To update the upstream version a local checkout of the Gz library is |
| 123 | + needed. A new branch is required to submit changes: |
| 124 | + |
| 125 | + ```bash |
| 126 | + # version X.Y.Z |
| 127 | + git checkout -b bump_to_X_Y_Z |
| 128 | + ``` |
| 129 | + |
| 130 | + 2. The current upstream version can be found in `CMakeLists.txt` file |
| 131 | + following the CMake `project declaration`: |
| 132 | + |
| 133 | + ```cmake |
| 134 | + # Gz library named foo and version X.Y.Z |
| 135 | + project(gz-fooX VERSION X.Y.Z) |
| 136 | + ``` |
| 137 | + |
| 138 | + Stable releases can modify the X, Y or Z directly while prereleases will need to include the preX (X number starts with 1) suffix in the `gz_configure_project`: |
| 139 | + |
| 140 | + ```cmake |
| 141 | + # first prerelease of a serie, number 1 |
| 142 | + gz_configure_project(VERSION_SUFFIX pre1) |
| 143 | + ``` |
| 144 | + |
| 145 | + 3. Together with bumping the version number, **updating the Changelog and Migration |
| 146 | + documents** is required. The `Changelog.md` file and `Migration.md` files |
| 147 | + are located at the top level of every Gz library. Modify them as needed. |
| 148 | + |
| 149 | + ```bash |
| 150 | + git commit CMakeList.xt |
| 151 | + git commit Changelog.md |
| 152 | + git commit Migration.md |
| 153 | + git push origin ... |
| 154 | + ``` |
| 155 | + |
| 156 | + 4. Open a pull request for reviewing ([example PR](https://github.com/gazebosim/gz-physics/pull/132)). |
| 157 | + Include a link comparing the current release branch to the |
| 158 | + latest release ([example of a branch comparison](https://github.com/gazebosim/gz-sim/compare/ignition-gazebo3_3.5.0...ign-gazebo3)). Releases are tagged in GitHub repositories with the scheme |
| 159 | + `ignition/gz-fooX_X.Y.Z` where foo is the name of the Gz library and X.Y.Z |
| 160 | + the code version. |
| 161 | + |
| 162 | +### Update packages version |
| 163 | + |
| 164 | +Once the PR for bumping the code version is merged, the binary packages version |
| 165 | +needs to be updated for the Debian/Ubuntu packages. Brew metadata will be |
| 166 | +updated by the building server when creating the binary packages |
| 167 | +(known as `bottles`). |
| 168 | + |
| 169 | +The version in the packages (binary version) should be similar to the one updated |
| 170 | +in the code in the step above but usually has some other components that reflect the |
| 171 | +package metadata version (i.e: new code version 2.1.0, new version in Debian packages |
| 172 | +is usually 2.1.0-1). |
| 173 | + |
| 174 | +There should be a repository matching the name and major version of Gz |
| 175 | +library that you want to bump in the |
| 176 | +[gz-release](https://github.com/gazebo-release/) GitHub organization. |
| 177 | +(see [release repositories document](releasing/release_repositories.md) for more |
| 178 | +information about how they are used). |
| 179 | + |
| 180 | +1. It is required to clone the corresponding release repository to update the |
| 181 | + binary version: |
| 182 | + |
| 183 | + ```bash |
| 184 | + # Gz library named foo and major version X |
| 185 | + git clone https://github.com/gazebo-release/gz-fooX-release |
| 186 | + ``` |
| 187 | + |
| 188 | +2. To bump the package versions that will appear in Debian/Ubuntu binary packages there is a helper script in `release-tools` (see [prerequisites](#prerequisites)). The script is called `changelog_spawn.sh` and require to be executed while the active directory is a `release repository`: |
| 189 | + |
| 190 | + ```bash |
| 191 | + # Gz library named foo and major version X |
| 192 | + cd gz-fooX-release |
| 193 | + ~/release-tools/release-repo-scripts/changelog_spawn.sh X.Y.Z-R |
| 194 | + |
| 195 | + # Example gz-cmake3 bumped from 3.0.0 to 3.0.1 |
| 196 | + cd gz-cmake3-release |
| 197 | + ~/release-tools/release-repo-scripts/changelog_spawn.sh 3.0.1-1 |
| 198 | + ``` |
| 199 | + |
| 200 | +`changelog_spawn.sh` will display information about the Ubuntu/Debian versions being updated as well as a `git diff` before uploading information to the GitHub release repository. |
| 201 | + |
| 202 | +## Triggering the release |
| 203 | + |
| 204 | +After updating the code and releasing metadata everything is ready to launch the |
| 205 | +build in the server. Now, the following needs to happen: |
| 206 | + |
| 207 | + 1. Generate a tarball with the Gz library sources corresponding to the new |
| 208 | + version in the Gz developer local system. Upload the tarball to S3 cloud storage. |
| 209 | + 1. Request `build.osrfoundation.org` server to start the jobs for: |
| 210 | + 1. Debian/Ubuntu: use `ign/gz-fooX-debbuilder` job names |
| 211 | + 1. Brew: entry job is `generic-release-homebrew_pull_request_updater` |
| 212 | + |
| 213 | +The `release.py` script will perform all these actions. |
| 214 | + |
| 215 | +### Executing release.py |
| 216 | + |
| 217 | +Make sure you are in the source code repository before running `release.py`. |
| 218 | +You should be on the branch to be released, after the pull request bumping |
| 219 | +the version has been merged (run `git status` to check the branch, and `git |
| 220 | + log` to check that the version bump pull request has been included). |
| 221 | +Running `release.py` from the source code repository will generate and |
| 222 | +upload some Git tags ("release tags") to the source code repository. |
| 223 | + |
| 224 | +You will also need the token described in the [credentials |
| 225 | +section](#credentials). |
| 226 | + |
| 227 | +**dry-run simulation mode** |
| 228 | + |
| 229 | +The `release.py` tool supports a `--dry-run` flag that allows users to |
| 230 | +simulate releases (nothing is modified) in order to ensure that the correct |
| 231 | +arguments are being used to trigger a particular release. Gz releasers |
| 232 | +should **always** call `release.py` with `--dry-run` first in order to |
| 233 | +ensure that proper commands are being used to trigger releases. |
| 234 | + |
| 235 | +The script needs to be run from the repository with the source code (i.e., the repository where the Gz library version bump pull request took place): |
| 236 | + |
| 237 | +```bash |
| 238 | +# Example of dry-run for gz-cmake3 bumped to 3.0.1 |
| 239 | +cd gz-cmake3 |
| 240 | +git checkout gz-cmake3 |
| 241 | +~/release-tools/release.py gz-cmake3 3.0.1 dry-run-fake-token --dry-run |
| 242 | +``` |
| 243 | + |
| 244 | +**release.py for stable releases** |
| 245 | + |
| 246 | +```bash |
| 247 | +# Gz library named foo and major version X |
| 248 | +cd ign/gz-fooX |
| 249 | +git checkout ign/gz-fooX |
| 250 | +
|
| 251 | +# Example gz-cmake3 bumped to 3.0.1 with jenkins_token credential |
| 252 | +cd gz-cmake3 |
| 253 | +git checkout gz-cmake3 |
| 254 | +# please replace <jenkins_token> with real release token (check crendentials section) |
| 255 | +~/release-tools/release-repo-scripts/release.py gz-cmake3 3.0.1 <jenkins_token> |
| 256 | +``` |
| 257 | + |
| 258 | +**release.py for prereleases or nightlies** |
| 259 | + |
| 260 | +When releasing prereleases or nightly releases, there are some special flags |
| 261 | +to be set. The `--upload-to-repo` argument is mandatory when running |
| 262 | +`release.py`, and should be set to `prerelease` or `nightly`. |
| 263 | + |
| 264 | +```bash |
| 265 | +# Example gz-cmake3 bumped to prerelease 3.0.0~pre1 with jenkins_token credential |
| 266 | +cd gz-cmake3 |
| 267 | +git checkout gz-cmake3 |
| 268 | +# please replace <jenkins_token> with real release token (check crendentials section) |
| 269 | +~/release-tools/release-repo-scripts/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo prerelease |
| 270 | +``` |
| 271 | + |
| 272 | +Nightly invocation is generally coded in the server. The version will be |
| 273 | +taken from the last changelog entry and modified during building. No source |
| 274 | +code will be uploaded, but taken directly in the binary build from the |
| 275 | +branch pointed by `--nightly-src-branch`. |
| 276 | + |
| 277 | +```bash |
| 278 | +# Example gz-cmake3 nightly from main branch with jenkins_token credential |
| 279 | +cd gz-cmake3 |
| 280 | +git checkout gz-cmake3 |
| 281 | +# please replace <jenkins_token> with real release token (check crendentials section) |
| 282 | +~/release-tools/release-repo-scripts/release.py gz-cmake3 3.0.0~pre1 <jenkins_token> --upload-to-repo nightly --nightly-src-branch main |
| 283 | +
|
| 284 | +``` |
| 285 | + |
| 286 | +**Binary version schema for prereleases and nightlies** |
| 287 | + |
| 288 | +Prerelease and nightlies binary versions use particular naming schema to define right |
| 289 | +ordering for package managers. [This information about versioning](https://classic.gazebosim.org/tutorials?tut=install_unstable&cat=install#Versioninginnightlyandprerelease) in Gazebo Classic applies to the [Gazebo] too. |
| 290 | + |
| 291 | +**release.py for revision bumps** |
| 292 | + |
| 293 | +Bumping the [revision number for binary packages](#versioning) is a special |
| 294 | +case of releasing since the original tarball with the source code will |
| 295 | +remain the same. Once the release repository is ready with the new release |
| 296 | +version, `release.py` needs the `--only-bump-revision-linux` flag: |
| 297 | + |
| 298 | +```bash |
| 299 | +# Example gz-cmake3 bumped from 3.0.1-1 to 3.0.1-2 with jenkins_token credential |
| 300 | +cd gz-cmake3 |
| 301 | +git checkout gz-cmake3 |
| 302 | +# please replace <jenkins_token> with real release token (check crendentials section) |
| 303 | +~/release-tools/release-repo-scripts/release.py gz-cmake3 3.0.1 <jenkins_token> --only-bump-revision-linux -release-version 2 |
| 304 | +``` |
| 305 | + |
| 306 | +## Checking the Building Process |
| 307 | + |
| 308 | +For checking that the build process is ongoing as expected: |
| 309 | + |
| 310 | +1. Several `-debbuilder` jobs should be in https://build.osrfoundation.org/. |
| 311 | + For watching the jobs to see if any of them fail or are marked unstable, |
| 312 | + open the page for a specific debbuild, such as |
| 313 | + https://build.osrfoundation.org/job/gz-math7-debbuilder/. |
| 314 | + |
| 315 | + 1. If there is a failure, check the list of supported |
| 316 | + architectures in the corresponding [Gazebo Platform Support issue](https://github.com/gazebo-tooling/release-tools/issues?q=label%3A%22Tier+Platform+Support%22+) |
| 317 | + |
| 318 | + 1. To check if a debbuild has previously succeeded for a given architecture, |
| 319 | + check packages.osrfoundation.org to see the most recent successful builds. |
| 320 | + (i.e most recent [Ubuntu builds of ignition-gazebo6](https://packages.osrfoundation.org/gazebo/ubuntu-stable/pool/main/i/ignition-gazebo6/) |
| 321 | + or the [Debian builds of ignition-gazebo6](https://packages.osrfoundation.org/gazebo/debian-stable/pool/main/i/ignition-gazebo6/). |
| 322 | + |
| 323 | + 1. If the failure is on a supported architecture, check the source repository for an existing report of this failure and if none |
| 324 | + exists, report the failure (see [gazebosim/gz-math#161](https://github.com/gazebosim/gz-math/issues/161) |
| 325 | + for an example). |
| 326 | + |
| 327 | + 1. If a build is unstable, check if it was unstable before this release and if it has already been reported. |
| 328 | + A common cause of unstable debbuilds is newly installed files that are not captured by the patterns in the `.install` |
| 329 | + files in the `-release` repository. This can be checked by searching for `dh_missing` in the console log of the |
| 330 | + unstable build and looking for a list of uninstalled files. Example pull requests that fix problems with `dh_missing` |
| 331 | + are [gazebo-release/gz-transport11-release#4](https://github.com/gazebo-release/gz-transport11-release/pull/4) |
| 332 | + and [gazebo-release/gz-tools-release#4](https://github.com/gazebo-release/gz-tools-release/pull/4). |
| 333 | + |
| 334 | +1. A pull request was opened to https://github.com/osrf/homebrew-simulation |
| 335 | + 1. This pull request may take a minute or two to open. |
| 336 | + 1. Once it is open, make a comment containing the text "build bottle". |
| 337 | + For further details, see the [README at osrf/homebrew-simulation](https://github.com/osrf/homebrew-simulation#to-build-bottles). |
0 commit comments