github.com/containers/podman/v4@v4.9.4/RELEASE_PROCESS.md (about) 1 # Podman Releases 2 3 ## Overview 4 5 Podman (and podman-remote) versioning is mostly based on [semantic-versioning 6 standards](https://semver.org). 7 Significant versions 8 are tagged, including *release candidates* (`rc`). 9 All relevant **minor** releases (`vX.Y`) have their own branches. The **latest** 10 development efforts occur on the *main* branch. Branches with a 11 *rhel* suffix are use for long-term support of downstream RHEL releases. 12 13 ## Release workflow expectations 14 15 * You have push access to the [upstream podman repository](https://github.com/containers/podman.git) 16 * You understand all basic `git` operations and concepts, like creating commits, 17 local vs. remote branches, rebasing, and conflict resolution. 18 * You have access to your public and private *GPG* keys. 19 * You have reliable internet access (i.e. not the public WiFi link at McDonalds) 20 * Other podman maintainers are online/available for assistance if needed. 21 * For a **major** release, you have 4-8 hours of time available, most of which will 22 be dedicated to writing release notes. 23 * For a **minor** or **patch** release, you have 2-4 hours of time available 24 (minimum depends largely on the speed/reliability of automated testing) 25 * You will announce the release on the proper platforms 26 (i.e. Podman blog, Twitter, Mastodon Podman and Podman-Desktop mailing lists) 27 28 # Prechecks 29 30 Two days before actually cutting a release (including RCs), send an announcement to the 31 [podman-desktop](mailto:podman-desktop@lists.podman.io) 32 mailing list about the upcoming release. This will help the Podman Desktop team test and schedule 33 their own new release. 34 35 # Releases 36 37 ## Major (***X***.y.z) release 38 39 These releases always begin from *main*, and are contained in a branch 40 named with the **major** and **minor** version. **Major** release branches 41 begin in a *release candidate* phase, with prospective release tags being 42 created with an `-rc` suffix. There may be multiple *release candidate* 43 tags before the final/official **major** version is tagged and released. 44 45 ## Significant minor (x.**Y**.z) and patch (x.y.**Z**) releases 46 47 Significant **minor** and **patch** level releases are normally 48 branched from *main*, but there are occasional exceptions. 49 Additionally, these branches may be named with `-rhel` (or another) 50 suffix to signify a specialized purpose. For example, `-rhel` indicates 51 a release intended for downstream *RHEL* consumption. 52 53 ## Unreleased Milestones 54 55 Non-release versions may occasionally appear tagged on a branch, without 56 the typical (major) receive media postings or artifact distribution. For 57 example, as required for the (separate) RHEL release process. Otherwise 58 these tags are simply milestones of reference purposes and may 59 generally be safely ignored. 60 61 ## Process 62 63 ***Note:*** This is intended as a guideline, and generalized process. 64 Not all steps are applicable in all situations. Not all steps are 65 spelled with complete minutiae. 66 67 1. Create a new upstream release branch (if none already exist). 68 69 1. Check if a release branch is needed. Typically, major and minor version bumps 70 should be branched sometime during the release candidate phase. Patch 71 releases typically already have a branch created. 72 Branching ensures all changes are curated before inclusion in the 73 release, and no new features land after the *release-candidate* phases 74 are complete. 75 1. Ensure your local clone is fully up to date with the remote upstream 76 (`git remote update`). Switch to this branch (`git checkout upstream/main`). 77 1. Make a new local branch for the release based on *main*. For example, 78 `git checkout -b vX.Y`. Where `X.Y` represent the complete release 79 version-name, including any suffix (if any) like `-rhel`. ***DO NOT*** 80 include any `-rc` suffix in the branch name. 81 1. Edit the `.cirrus.yml` file, changing the `DEST_BRANCH` value (under the 82 `env` section) to the new, complete branch name (e.x. `vX.Y`). 83 Commit and sign, using the description 84 `Cirrus: Update operating branch`. 85 1. Push the new branch otherwise unmodified (`git push upstream vX.Y`). 86 1. Automation will begin executing on the branch immediately. Because 87 the repository allows out-of-sequence PR merging, it is possible that 88 merge order introduced bugs/defects. To establish a clean 89 baseline, observe the initial CI run on the branch for any unexpected 90 failures. This can be done by going directly to 91 `https://cirrus-ci.com/github/containers/podman/vX.Y` 92 1. If there are CI test or automation boops that need fixing on the branch, 93 attend to them using normal PR process (to *main* first, then backport 94 changes to the new branch). Ideally, CI should be "green" on the new 95 branch before proceeding. 96 97 1. Create a new branch-verification Cirrus-Cron entry. 98 99 1. This is to ensure CI's VM image timestamps are refreshed. Without this, 100 the VM images ***will*** be permanently pruned after 60 days of inactivity 101 and are hard/impossible to re-create accurately. 102 1. Go to 103 [https://cirrus-ci.com/github/containers/podman](https://cirrus-ci.com/github/containers/podman) 104 and press the "gear" (Repository Settings) button on the top-right. 105 1. At the bottom of the settings page is a table of cron-job names, branches, 106 schedule, and recent status. Below that is an editable new-entry line. 107 1. Set the new job's `name` and `branch` to the name of new release branch. 108 1. Set the `expression` using the form `X X X ? * 1-6` where 'X' is a number 109 between 0-23 and not already taken by another job in the table. The 1-hour 110 interval is used because it takes about that long for the job to run. 111 1. Add the new job by pressing the `+` button on the right-side of the 112 new-entry line. 113 114 115 1. Create a new local working-branch to develop the release PR 116 1. Ensure your local clone is fully up to 117 date with the remote upstream (`git remote update`). 118 1. Create a local working branch based on `upstream/main` or the correct upstream branch. 119 Example: `git checkout -b bump_vX.Y.Z --no-track upstream/vX.Y` 120 121 1. Compile release notes. 122 123 1. Ensure any/all intended PR's are completed and merged prior to any 124 processing of release notes. 125 1. Find all commits since the last release. There is a script, `/hack/branch_commits.rb` 126 that is helpful for finding all commits in one branch, but not in another, 127 accounting for cherry-picks. Commits in base branch that are not in 128 the old branch will be reported. `ruby branch_commits.rb upstream/main upstream/vX.Y` 129 Keep this list open/available for reference as you edit. 130 1. Edit `RELEASE_NOTES.md` 131 132 * Add/update the version-section of with sub-sections for *Features* 133 (new functionality), *Changes* (Altered podman behaviors), 134 *Bugfixes* (self-explanatory), *API* (All related features, 135 changes, and bugfixes), and *Misc* (include any **major** 136 library bumps, e.g. `c/buildah`, `c/storage`, `c/common`, etc). 137 * Use your merge-bot reference PR-listing to examine each PR in turn, 138 adding an entry for it into the appropriate section. 139 * Use the list of commits to find the PR that the commit came from. 140 Write a release note if needed. 141 142 * Use the release note field in the PR as a guideline. 143 It may be helpful but also may need rewording for consistency. 144 Some PR's with a release note field may not need one, and some PR's 145 without a release note field may need one. 146 * Be sure to link any issue the PR fixed. 147 * Do not include any PRs that are only documentation or test/automation 148 changes. 149 * Do not include any PRs that fix bugs which we introduced due to 150 new features/enhancements. In other words, if it was working, broke, then 151 got fixed, there's no need to mention those items. 152 153 1. Commit the `RELEASE_NOTES.md` changes, using the description 154 `Create release notes for vX.Y.Z` (where `X`, `Y`, and `Z` are the 155 actual version numbers). 156 1. Open a Release Notes PR, or include this commit with the version bump PR 157 * If you decide to open a PR with just release notes, make sure that 158 the commit has the prefix `[CI:DOCS]` to avoid triggering 159 lengthy automated testing. 160 * Otherwise, the release notes commit can also be included in the 161 following release PR. 162 163 1. Update version numbers and push tag 164 165 1. Edit `version/rawversion/version.go` and bump the `Version` value to the new 166 release version. If there were API changes, also bump `APIVersion` value. 167 Make sure to also bump the version in the swagger.yaml `pkg/api/server/docs.go` 168 For major and minor versions also add the new branch name to 169 `docs/source/Reference.rst` to show the new swagger version on docs.podman.io. 170 1. Commit this and sign the commit (`git commit -a -s -S`). The commit message 171 should be `Bump to vX.Y.Z` (using the actual version numbers). 172 1. Push this single change to your GitHub fork, and make a new PR, 173 **being careful** to select the proper release branch as its base. 174 1. Wait for all automated tests pass (including on an RC-branch PR). Re-running 175 and/or updating code as needed. 176 1. In the PR, under the *Checks* tab, locate and clock on the Cirrus-CI 177 task `Optional Release Test`. In the right-hand window pane, click 178 the `trigger` button and wait for the test to go green. *This is a 179 critical step* which confirms the commit is worthy of becoming a release. 180 1. Tag the `Bump to vX.Y.Z` commit as a release by running 181 `git tag -s -m 'vX.Y.Z' vX.Y.Z $HASH` where `$HASH` is specified explicitly 182 and carefully, to avoid (basically) unfixable accidents (if they are pushed). 183 1. Change `version/rawversion/version.go` again. This time, bump the **patch** version and 184 re-add the `-dev` suffix to indicate this is a non-released version of Podman. 185 1. Change `contrib/spec/podman.spec.in`, bumping **patch** number of `Version`. 186 1. Commit these changes with the message `Bump to X.Y.Z-dev`. 187 1. Push your local branch to your GitHub fork (and the PR) again. 188 1. The PR should now have two commits that look very similar to 189 https://github.com/containers/podman/pull/7787 190 Note: Backports and release note commits may also be included in the release PR. 191 1. Wait for at least all the "Build" and "Verify" (or similar) CI Testing 192 steps to complete successfully. No need to wait for complete integration 193 4and system-testing (it was already done on substantially the same code, above). 194 1. Merge the PR (or ask someone else to review and merge, to be safer). 195 1. **Note:** This is the last point where any test-failures can be addressed 196 by code changes. After pushing the new version-tag upstream, no further 197 changes can be made to the code without lots of unpleasant efforts. Please 198 seek assistance if needed, before proceeding. 199 200 1. Assuming the "Bump to ..." PR merged successfully, and you're **really** 201 confident the correct commit has been tagged, push it with 202 `git push upstream vX.Y.Z` 203 204 1. Locate, Verify release testing is proceeding 205 206 1. When the tag was pushed, an automated build was created. Locate this 207 by starting from 208 `https://github.com/containers/podman/tags` and finding the recent entry 209 for the pushed tag. Under the tag name will be a timestamp and abbrieviated 210 commit hash, for example `<> 5b2585f`. Click the commit-hash link. 211 1. In the upper-left most corner, just to the left of the "Bump to vX.Y" 212 text, will be a small status icon (Yellow circle, Red "X", or green check). 213 Click this, to open a small pop-up/overlay window listing all the status 214 checks. 215 1. In the small pop-up/overlay window, press the "Details" link on one of the 216 Cirrus-CI status check entries (doesn't matter which one). 217 1. On the following page, in the lower-right pane, will be a "View more details 218 on Cirrus CI" link, click this. 219 1. A Cirrus-CI task details page will open, click the button labeled 220 "View All Tasks". 221 1. Keep this page open to monitor its progress and for use in future steps. 222 223 1. Bump main `-dev` version 224 225 1. If you made a release branch and bumped **major** or **minor** version 226 Complete the "Update version numbers and push tag" steps above on the 227 *main* branch. Bump the **minor** version and set the **patch** 228 version to 0. For example, after pushing the v2.2.0 release, *main* 229 should be set to v2.3.0-dev. 230 1. Create a "Bump to vX.Y.Z-dev" commit with these changes. 231 1. Update `RELEASE_NOTES.md` on main. Commit these changes. 232 1. Create a PR with the above commits, and oversee it's merging. 233 234 1. Create Github Release entry and upload assets 235 236 1. Return to the Cirrus-CI Build page for the new release tag, confirm 237 (or wait for) it to complete, re-running any failed tasks as appropriate. 238 1. For anything other than an RC, the release artifacts need to be published along 239 with the release. These can be built locally using: 240 241 ```shell 242 $ git checkout vX.Y.Z 243 $ make release-artifacts 244 ``` 245 246 1. In the directory where you downloaded the archives, run 247 `sha256sum *.tar.gz *.zip > shasums` to generate SHA sums. 248 1. Go to `https://github.com/containers/podman/releases/tag/vX.Y.Z` and 249 press the "Edit Release" button. Change the name to the form `vX.Y.Z` 250 1. If this is a release candidate be certain to click the pre-release 251 checkbox at the bottom of the page. 252 1. If this new release will be the latest version released, be certain to 253 click the latest release checkbox at the bottom of the page. 254 1. Copy and paste the release notes for the release into the body of 255 the release. 256 1. Near the bottom of the page there is a box with the message 257 “Add binaries by dropping them here or selecting them”. Use 258 that to upload the artifacts in the `release/` dir generated earlier, 259 as well as the two Mac pkginstallers: 260 261 * podman-remote-release-darwin_amd64.zip 262 * podman-remote-release-darwin_arm64.zip 263 * podman-remote-release-windows_amd64.zip 264 * podman-vX.Y.Z.msi 265 * podman-remote-static-linux_amd64.tar.gz 266 * podman-remote-static-linux_arm64.tar.gz 267 * podman-installer-macos-amd64.pkg 268 * podman-installer-macos-arm64.pkg 269 * shasums 270 271 1. Click the Publish button to make the release (or pre-release) 272 available. 273 1. Check the "Actions" tab, after the publish you should see a job 274 automatically launch to build the Windows installer and the Mac Installer (named after 275 the release). There may be more than one running due to the multiple 276 event states triggered, but this can be ignored, as any duplicates 277 will gracefully back-off. The job takes 5-6 minutes to complete. 278 1. Confirm the podman-[version]-setup.exe file is now on the release 279 page. This might not be the case if you accidentally published the 280 release before uploading the binaries, as the job may look before 281 they are available. If that happens, you can either manually kick 282 off the job (see below), or just make a harmless edit to the 283 release (e.g. add an extra whitespace character somewhere). As 284 long as the body content is different in some way, a new run will 285 be triggered. 286 287 ## Manually Triggering Windows Installer Build & Upload 288 289 ### *CLI Approach* 290 1. Install the [GitHub CLI](https://github.com/cli/cli#installation) 291 1. Run (replacing below version number to release version) 292 ``` 293 gh workflow run "Upload Windows Installer" -F version="v4.2.0" 294 ``` 295 ### *GUI Approach* 296 1. Go to the "Actions" tab 297 1. On the left pick the "Update Windows Installer" category 298 1. A blue box will appear above the job list with a right side drop 299 -down. Click the drop-down and specify the version number in the 300 dialog that appears 301 302 ## Manually Triggering Mac Installer Build & Upload 303 304 ### *CLI Approach* 305 1. Install the [GitHub CLI](https://github.com/cli/cli#installation) 306 1. Run (replacing below version number to release version) 307 ``` 308 gh workflow run "Sign and Upload Mac Installer" -F version="v4.2.0" 309 ``` 310 ### *GUI Approach* 311 1. Go to the "Actions" tab 312 1. On the left pick the "Sign and Upload Mac Installer" category 313 1. A blue box will appear above the job list with a right side drop 314 -down. Click the drop-down and specify the version number in the 315 dialog that appears 316 317 1. Announce the release 318 1. For major and minor releases, write a blog post and publish it to blogs.podman.io 319 Highlight key features and important changes or fixes. Link to the GitHub release. 320 Make sure the blog post is properly tagged with the Announcement, Release, and Podman tags, 321 and any other appropriate tags. 322 1. For all releases, including patch releases and RC's, send an email to the [podman](mailto:podman@lists.podman.io) and [podman-desktop](mailto:podman-desktop@lists.podman.io) mailing lists. 323 Link the to release blog and GitHub release. 324 1. Update [LATEST_VERSION](https://github.com/containers/podman.io/blob/main/static/data/global.ts) on the Podman.io website. 325 1. Tweet the release. Make a Mastodon post about the release. 326 1. RC's can also be announced if needed.