Merge pull request #1640 from Nordix/tuomo/update-release-docs

📖 update releasing docs

docs/releasing.md

@@ -7,19 +7,19 @@ BMO.
 [release documentation from the main branch](https://github.com/metal3-io/baremetal-operator/blob/main/docs/releasing.md).
 Release documentation in release branches may be outdated.
 
-**NOTE**: release branches are not in use yet, tags are done directly on the
-main branch.
-
 ## Before making a release
 
 Things you should check before making a release:
 
 - Check the
   [Metal3 release process](https://github.com/metal3-io/metal3-docs/blob/main/processes/releasing.md)
   for high-level process and possible follow-up actions
-- Verify controller Go modules use latest corresponding CAPI modules
-- Verify any other direct or indirect dependency is uplifted to close any public
-  vulnerabilities
+- Use the `./hack/verify-release.sh` script as helper to identify possible
+  issues to be addressed before creating any release tags. It verifies issues
+  like:
+   - Verify controller Go modules use latest corresponding CAPI modules
+   - Verify any other direct or indirect dependency is uplifted to close any public
+     vulnerabilities
 
 ## Permissions
 
@@ -38,7 +38,11 @@ given permissions directly.
 
 ## Process
 
-BMO uses [semantic versioning](https://semver.org). For version `v0.x.y`:
+BMO uses [semantic versioning](https://semver.org).
+
+- Regular releases: `v0.x.y`
+- Beta releases: `v0.x.y-beta.z`
+- Release candidate releases: `v0.x.y-rc.z`
 
 ### Repository setup
 
@@ -67,15 +71,18 @@ This triggers two things:
 - GitHub action workflow for automated release process creates a draft release
   in GitHub repository with correct content, comparing the pushed tag to
   previous tag. Running actions are visible on the
-  [Actions](https://github.com/metal3-io/baremetal-operator/actions) page, and
-  draft release will be visible on top of the
-  [Releases](https://github.com/metal3-io/baremetal-operator/releases) page.
-- Quay starts building release image with the release tag. Make sure the release
-  is built successfully in
-  [Quay builds page](https://quay.io/repository/metal3-io/baremetal-operator?tab=builds).
-  If the release tag build is not visible, check if the build trigger is
-  enabled. Quay disables build trigger sometimes when build has failed few
-  times.
+  [Actions](https://github.com/metal3-io/baremetal-operator/actions)
+  page, and draft release will be visible on top of the
+  [Releases](https://github.com/metal3-io/baremetal-operator/releases)
+  page.
+- GH action `build-images-action` starts building release image with the release
+  tag in Jenkins, and it gets pushed to Quay. Make sure the release tag is
+  visible in
+  [Quay tags page](https://quay.io/repository/metal3-io/baremetal-operator?tab=tags).
+  If the release tag build is not visible, check if the action has failed and
+  retrigger as necessary. Also
+  [keepalived](https://quay.io/repository/metal3-io/keepalived?tab=tags) is
+  built and tagged.
 
 We also need to create one or more tags for the Go modules ecosystem:
 
@@ -87,11 +94,36 @@ We also need to create one or more tags for the Go modules ecosystem:
   modules. Release notes expects only the main tag to be annotated, otherwise it
   might create incorrect release notes.
 
+### Release notes
+
+Next step is to clean up the release note manually. Release note has been
+generated by the `release` action, do not click the `Generate release notes`
+button. In case there is issue with release action, you may rerun it via
+`Actions` tab, or you can `make release-notes` to get a markdown file with
+the release content to be inserted.
+
+- If release is not a beta or release candidate, check for duplicates, reverts,
+  and incorrect classifications of PRs, and whatever release creation tagged to
+  be manually checked.
+   - For any superseded PRs (like same dependency uplifted multiple times, or
+     commit revertions) that provide no value to the release, move them to
+     Superseded section. This way the changes are acknowledged to be part of the
+     release, but not overwhelming the important changes contained by the
+     release.
+- If the release you're making is not a new major release, new minor release,
+  or a new patch release from the latest release branch, uncheck the box for
+  latest release.
+- If it is a release candidate (RC) or a beta release, tick pre-release box.
+- Save the release note as a draft, and have others review it.
+
 ### Release artifacts
 
 We need to verify all release artifacts are correctly built or generated by the
 release workflow. For a release, we should have the following artifacts:
 
+We can use `./hack/verify-release.sh` to check for existence of release artifacts,
+which should include the following:
+
 Git tags pushed:
 
 - Primary release tag: `v0.x.y`
@@ -106,21 +138,10 @@ Files included in the release page:
 
 - Source code
 
-### Release notes
+### Make the release
 
-Next step is to clean up the release note manually.
-
-- Check for duplicates, reverts, and incorrect classifications of PRs, and
-  whatever release creation tagged to be manually checked.
-- For any superseded PRs (like same dependency uplifted multiple times, or
-  commit revertions) that provide no value to the release, move them to
-  Superseded section. This way the changes are acknowledged to be part of the
-  release, but not overwhelming the important changes contained by the release.
-- If the release you're making is not a new major release, new minor release, or
-  a new patch release from the latest release branch, uncheck the box for latest
-  release.
-- If it is a release candidate (RC) or a pre-release, tick pre-release box.
-- Publish the release.
+After everything is checked out, hit the `Publish` button your GitHub draft
+release!
 
 ## Post-release actions for new release branches