Skip to content

Commit

Permalink
Merge pull request #18272 from ashley-cui/reldoc
Browse files Browse the repository at this point in the history 
[CI:DOCS] Update RELEASE_PROCESS.md
  • Loading branch information
@openshift-ci
openshift-ci[bot] authored Apr 20, 2023
2 parents c263c18 + 3464837 commit 08a0cc3
Showing 1 changed file with 119 additions and 89 deletions.
208 changes: 119 additions & 89 deletions RELEASE_PROCESS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ development efforts occur on the *main* branch. Branches with a
be dedicated to writing release notes.
* For a **minor** or **patch** release, you have 2-4 hours of time available
(minimum depends largely on the speed/reliability of automated testing)
* You will annouce the release on the proper platforms
(i.e. Podman blog, Twitter, Mastodon Podman and Podman-Desktop mailing lists)

# Releases

Expand Down Expand Up @@ -55,65 +57,17 @@ generally be safely ignored.
Not all steps are applicable in all situations. Not all steps are
spelled with complete minutiae.

1. Make a `[CI:DOCS]` release notes pull request.

1. Ensure any/all intended PR's are completed and merged prior to any
processing of release notes. Ensure your local clone is fully up to
date with the remote upstream (`git remote update`).
1. Check out (create) a local working branch for a release-notes PR,
based on the latest `upstream/main` or pre-existing version-named
branch - for example, if this is an additional *release-candidate*
you might use `vX.Y.Z-rc2`; **Note** this is a local branch name,
an upstream branch would never contain the `-rc?` suffix.
1. Find all merged PRs since the last release, which were performed by
the merge-robot. For example, given the commit range `1234...5678`
you would run `git log --oneline --author=openshift-merge-robot 1234...5678`.
Keep this list open/available for reference as you edit.
1. Edit `RELEASE_NOTES.md`

* If operating on a *release-candidate*, be sure to remove any
not-applicable items/sections. For example, those brought in
because of backports.
* Add/update the version-section of with sub-sections for *Features*
(new functionality), *Changes* (Altered podman behaviors),
*Bugfixes* (self-explanatory), *API* (All related features,
changes, and bugfixes), and *Misc* (include any **major**
library bumps, e.g. `c/buildah`, `c/storage`, `c/common`, etc).
* Use your merge-bot reference PR-listing to examine each PR in turn,
adding an entry for it into the appropriate section.

* Be sure to link any issue the PR fixed.
* Do not include any PRs that are only documentation or test/automation
changes.
* Do not include any PRs that fix bugs which we introduced due to
new features/enhancements. In other words, if it was working, broke, then
got fixed, there's no need to mention those items.

1. Commit and **sign** the `RELEASE_NOTES.md` changes, using the description
`Create release notes for vX.Y.Z` (where `X`, `Y`, and `Z` are the
actual version numbers).
1. Push your working branch to your github fork and create a new pull request.

* ***Ensure*** you properly select the base branch if not *main*.
For example, `vX.y.Z`.
* ***Before submitting*** the new PR, update the title with the
prefix `[CI:DOCS]` to avoid triggering lengthy automated testing.

1. If this is a release on a pre-existing version-named branch
(e.x. *release-candidate* or `-rhel`), open another PR against
the upstream *main* branch. This is needed to ensure the new
notes are present for future releases.


1. Create a new upstream release branch (if none already exist).

1. After the release-notes pull requests have merged, a release branch is
needed. Branching ensures all changes are curated before inclusion in the
1. Check if a release branch is needed. Typically, major and minor version bumps
should be branched sometime during the release candidate phase. Patch
releases typically already have a branch created.
Branching ensures all changes are curated before inclusion in the
release, and no new features land after the *release-candidate* phases
are complete.
1. Ensure your local clone is fully up to date with the remote upstream
(`git remote update`). Switch to this branch (`git checkout upstream/main`).
1. Make a new local branch for the release based on *main*. For example,
1. Make a new local branch for the release based on *main*. For example,
`git checkout -b vX.Y`. Where `X.Y` represent the complete release
version-name, including any suffix (if any) like `-rhel`. ***DO NOT***
include any `-rc` suffix in the branch name.
Expand All @@ -133,44 +87,80 @@ spelled with complete minutiae.
changes to the new branch). Ideally, CI should be "green" on the new
branch before proceeding.

1. Create a new branch-verification Cirrus-Cron entry.

1. This is to ensure CI's VM image timestamps are refreshed. Without this,
the VM images ***will*** be permanently pruned after 60 days of inactivity
and are hard/impossible to re-create accurately.
1. Go to
[https://cirrus-ci.com/github/containers/podman](https://cirrus-ci.com/github/containers/podman)
and press the "gear" (Repository Settings) button on the top-right.
1. At the bottom of the settings page is a table of cron-job names, branches,
schedule, and recent status. Below that is an editable new-entry line.
1. Set the new job's `name` and `branch` to the name of new release branch.
1. Set the `expression` using the form `X X X ? * 1-6` where 'X' is a number
between 0-23 and not already taken by another job in the table. The 1-hour
interval is used because it takes about that long for the job to run.
1. Add the new job by pressing the `+` button on the right-side of the
new-entry line.
1. Create a new branch-verification Cirrus-Cron entry.

1. This is to ensure CI's VM image timestamps are refreshed. Without this,
the VM images ***will*** be permanently pruned after 60 days of inactivity
and are hard/impossible to re-create accurately.
1. Go to
[https://cirrus-ci.com/github/containers/podman](https://cirrus-ci.com/github/containers/podman)
and press the "gear" (Repository Settings) button on the top-right.
1. At the bottom of the settings page is a table of cron-job names, branches,
schedule, and recent status. Below that is an editable new-entry line.
1. Set the new job's `name` and `branch` to the name of new release branch.
1. Set the `expression` using the form `X X X ? * 1-6` where 'X' is a number
between 0-23 and not already taken by another job in the table. The 1-hour
interval is used because it takes about that long for the job to run.
1. Add the new job by pressing the `+` button on the right-side of the
new-entry line.


1. Create a new local working-branch to develop the release PR
1. Ensure your local clone is fully up to
date with the remote upstream (`git remote update`).
1. Create a local working branch based on `upstream/main` or the correct upstream branch.
Example: `git checkout -b bump_vX.Y.Z --no-track upstream/vX.Y`

1. Compile release notes.

1. Ensure any/all intended PR's are completed and merged prior to any
processing of release notes.
1. Find all commits since the last release. There is a script, `/hack/branch_commits.rb`
that is helpful for finding all commits in one branch, but not in another,
accounting for cherry-picks. Commits in base branch that are not in
the old branch will be reported. `ruby branch_commits.rb upstream/main upstream/vX.Y`
Keep this list open/available for reference as you edit.
1. Edit `RELEASE_NOTES.md`

* Add/update the version-section of with sub-sections for *Features*
(new functionality), *Changes* (Altered podman behaviors),
*Bugfixes* (self-explanatory), *API* (All related features,
changes, and bugfixes), and *Misc* (include any **major**
library bumps, e.g. `c/buildah`, `c/storage`, `c/common`, etc).
* Use your merge-bot reference PR-listing to examine each PR in turn,
adding an entry for it into the appropriate section.
* Use the list of commits to find the PR that the commit came from.
Write a release note if needed.

* Use the release note field in the PR as a guideline.
It may be helpful but also may need rewording for consistency.
Some PR's with a release note field may not need one, and some PR's
without a release note field may need one.
* Be sure to link any issue the PR fixed.
* Do not include any PRs that are only documentation or test/automation
changes.
* Do not include any PRs that fix bugs which we introduced due to
new features/enhancements. In other words, if it was working, broke, then
got fixed, there's no need to mention those items.

1. Commit the `RELEASE_NOTES.md` changes, using the description
`Create release notes for vX.Y.Z` (where `X`, `Y`, and `Z` are the
actual version numbers).
1. Open a Release Notes PR, or include this commit with the version bump PR
* If you decide to open a PR with just release notes, make sure that
the commit has the prefix `[CI:DOCS]` to avoid triggering
lengthy automated testing.
* Otherwise, the release notes commit can also be included in the
following release PR.

1. Update version numbers and push tag

**TODO:** This process can be simplified by updating the script for the
"Optional Release Test" such that it tests the first commit, not the second.
In this way, pushing twice to the same PR won't be required.

1. Assuming CI Test and automation ran clean on the release branch,
update your local repo to be fully up to date with the remote upstream
(`git remote update`). Check out a local copy of the upstream
release branch (`git checkout upstream/vX.Y`).
1. Create a new local working-branch to develop the release PR,
`git checkout -b bump_vX.Y.Z`.
1. Look up the *COMMIT ID* of the last release,
`git log -1 $(git tag | sort -V | tail -1)`.
1. Edit `version/rawversion/version.go` and bump the `Version` value to the new
release version. If there were API changes, also bump `APIVersion` value.
Make sure to also bump the version in the swagger.yaml `pkg/api/server/docs.go`
and to add a new entry in `docs/source/Reference.rst` for major and minor releases.
1. Commit this and sign the commit (`git commit -a -s -S`). The commit message
should be `Bump to vX.Y.Z` (using the actual version numbers).
1. Push this single change to your github fork, and make a new PR,
1. Push this single change to your GitHub fork, and make a new PR,
**being careful** to select the proper release branch as its base.
1. Wait for all automated tests pass (including on an RC-branch PR). Re-running
and/or updating code as needed.
Expand All @@ -185,9 +175,10 @@ spelled with complete minutiae.
re-add the `-dev` suffix to indicate this is a non-released version of Podman.
1. Change `contrib/spec/podman.spec.in`, bumping **patch** number of `Version`.
1. Commit these changes with the message `Bump to X.Y.Z-dev`.
1. Push your local branch to your github fork (and the PR) again.
1. Push your local branch to your GitHub fork (and the PR) again.
1. The PR should now have two commits that look very similar to
https://github.com/containers/podman/pull/7787
Note: Backports and release note commits may also be included in the release PR.
1. Wait for at least all the "Build" and "Verify" (or similar) CI Testing
steps to complete successfully. No need to wait for complete integration
4and system-testing (it was already done on substantially the same code, above).
Expand Down Expand Up @@ -230,6 +221,7 @@ spelled with complete minutiae.
1. Create a "Bump to vX.Y.Z-dev" commit with these changes.
1. Bump the version number in `README.md` (still on on *main*)
to reflect the new release. Commit these changes.
1. Update `RELEASE_NOTES.md` on main. Commit these changes.
1. Create a PR with the above commits, and oversee it's merging.

1. Create Github Release entry and upload assets
Expand All @@ -244,10 +236,34 @@ spelled with complete minutiae.
$ make release-artifacts
```

1. The `podman-vX.Y.Z.dmg` file is produced manually by someone in
possession of a developer signing key.
1. In the directory where you downloaded the archives, run
`sha256sum *.tar.gz *.zip > shasums` to generate SHA sums.
1. Build the Mac pkginstaller. Note that this needs to be built
on a Mac with the correct DevID signing credentials. The
installers will be built to `/contrib/pkginstaller/out`Add the
shasums of `podman-installer-macos-amd64.pkg` and
`podman-installer-macos-arm64.pkg` to the `shasums` file.
```shell
$ git checkout vX.Y.Z
$ cd contrib/pkginstaller
$ make ARCH=amd64 \
CODESIGN_IDENTITY=$DevAppID \
PRODUCTSIGN_IDENTITY=$DevInsID \
NOTARIZE_USERNAME=$AppleAcc \
NOTARIZE_PASSWORD=$AppleAccPwd \
NOTARIZE_TEAM=$DevTeam \
notarize
$ make ARCH=aarch64 \
CODESIGN_IDENTITY=$DevAppID \
PRODUCTSIGN_IDENTITY=$DevInsID \
NOTARIZE_USERNAME=$AppleAcc \
NOTARIZE_PASSWORD=$AppleAccPwd \
NOTARIZE_TEAM=$DevTeam \
notarize
```
1. Go to `https://github.com/containers/podman/releases/tag/vX.Y.Z` and
press the "Edit Release" button. Change the name to the form `vX.Y.Z`
1. If this is a release candidate be certain to click the pre-release
Expand All @@ -257,15 +273,20 @@ spelled with complete minutiae.
1. Copy and paste the release notes for the release into the body of
the release.
1. Near the bottom of the page there is a box with the message
“Add binaries by dropping them here or selecting them”. Use
that to upload the artifacts in the `release/` dir generated earlier:
“Add binaries by dropping them here or selecting them”. Use
that to upload the artifacts in the `release/` dir generated earlier,
as well as the two Mac pkginstallers:

* podman-remote-release-darwin_amd64.zip
* podman-remote-release-darwin_arm64.zip
* podman-remote-release-windows_amd64.zip
* podman-vX.Y.Z.msi
* podman-remote-static-linux_amd64.tar.gz
* podman-remote-static-linux_arm64.tar.gz
* podman-installer-macos-amd64.pkg
* podman-installer-macos-arm64.pkg
* shasums

1. Click the Publish button to make the release (or pre-release)
available.
1. Check the "Actions" tab, after the publish you should see a job
Expand All @@ -284,7 +305,6 @@ spelled with complete minutiae.

## Manually Triggering Windows Installer Build & Upload


### *CLI Approach*
1. Install the GitHub CLI (e.g. `sudo dnf install gh`)
1. Run (replacing below version number to release version)
Expand All @@ -297,3 +317,13 @@ spelled with complete minutiae.
1. A blue box will appear above the job list with a right side drop
-down. Click the drop-down and specify the version number in the
dialog that appears

1. Announce the release
1. For major and minor releases, write a blog post and publish it to blogs.podman.io
Highlight key features and important changes or fixes. Link to the GitHub release.
Make sure the blog post is properly tagged with the Announcement, Release, and Podman tags,
and any other appropriate tags.
1. Send an email to the podman and podman-desktop mailing lists.
Link the to release blog and GitHub release.
1. Tweet the release. Make a Mastodon post about the release.
1. RC's can also be announced if needed.

0 comments on commit 08a0cc3

Please sign in to comment.