update releasing doc

Update releasing doc to be more clear, update the container build
process to match current workflow, highlight the verify-release.sh
usage more etc.

Signed-off-by: Tuomo Tanskanen <[email protected]>

Author: tuminoid

docs/releasing.md

@@ -14,25 +14,25 @@ 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 CAPI go module is uplifted in root, `api/` and `test/` go modules and
-  `cluster-api/test` module in `test/` go module. Prior art:
-  [#1157](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1157)
-- Verify controller Go modules use latest corresponding CAPI modules. Prior art:
-  [#1145](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1145)
-- Verify BMO's `apis` and `pkg/hardwareutils` dependencies are the latest. Prior
-  art:
-  [#1163](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1163)
-- Uplift IPAM `api` dependency,
-  [container image version](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/config/ipam/image_patch.yaml)
-  , and
-  [manifest resource](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/config/ipam/kustomization.yaml)
-  . Prior art:
-  [#999](https://github.com/metal3-io/cluster-api-provider-metal3/pull/999)
-- 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.
+- 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 CAPI go module is uplifted in root, `api/` and `test/` go modules and
+    `cluster-api/test` module in `test/` go module. Prior art:
+    [#1157](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1157)
+   - Verify controller Go modules use latest corresponding CAPI modules. Prior art:
+     [#1145](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1145)
+   - Verify BMO's `apis` and `pkg/hardwareutils` dependencies are the latest. Prior
+     art:
+     [#1163](https://github.com/metal3-io/cluster-api-provider-metal3/pull/1163)
+   - Uplift IPAM `api` dependency,
+     [container image version](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/config/ipam/image_patch.yaml)
+     , and
+     [manifest resource](https://github.com/metal3-io/cluster-api-provider-metal3/blob/main/config/ipam/kustomization.yaml)
+     . Prior art:
+     [#999](https://github.com/metal3-io/cluster-api-provider-metal3/pull/999)
+   - Verify any other direct or indirect dependency is uplifted to close any
+     public vulnerabilities
 
 ## Permissions
 
@@ -51,7 +51,11 @@ should not be given permissions directly.
 
 ## Process
 
-CAPM3 uses [semantic versioning](https://semver.org). For version `v1.x.y`:
+CAPM3 uses [semantic versioning](https://semver.org).
+
+- Regular releases: `v1.x.y`
+- Beta releases: `v1.x.y-beta.z`
+- Release candidate releases: `v1.x.y-rc.z`
 
 ### Repository setup
 
@@ -85,11 +89,12 @@ This triggers two things:
   page, and draft release will be visible on top of the
   [Releases](https://github.com/metal3-io/cluster-api-provider-metal3/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/cluster-api-provider-metal3?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.
+- 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/cluster-api-provider-metal3?tab=tags).
+  If the release tag build is not visible, check if the action has failed and
+  retrigger as necessary.
 
 We also need to create one or more tags for the Go modules ecosystem:
 
@@ -103,17 +108,36 @@ We also need to create one or more tags for the Go modules ecosystem:
   otherwise it might create incorrect release notes. Push both of the tags to
   `origin`.
 
+### Release notes
+
+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.
+- 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:
+the release workflow.
+
+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: `v1.x.y`
 - Go module tags: `api/v1.x.y`, `test/v1.x.y`
 
-Container images built and tagged at Quay registry:
+Container images at Quay registry:
 
 - [cluster-api-provider-metal3:v1.x.y](https://quay.io/repository/metal3-io/cluster-api-provider-metal3?tab=tags)
 
@@ -124,23 +148,10 @@ Files included in the release page:
 - A cluster template - `cluster-template.yaml`
 - A file containing an example of variables to set - `example_variables.rc`
 
-### Release notes
-
-Next step is to clean up the release note manually.
+### Make the release
 
-- 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.
-- Save the release note as a draft, and have others review it. Use the
-  `./hack/verify-release.sh` script as helper to verify release content.
-- Publish the release.
+After everything is checked out, hit the `Publish` button your GitHub draft
+release!
 
 ## Post-release actions for new release branches
 
@@ -155,6 +166,7 @@ keywords are implemented in Jenkins JJB, and in project-infra, and have been run
 at least once in the PR targeting the branch in question.
 
 NOTE: Branch protection rules need repository `admin` rights to modify.
+Organization admins and security team members can help you.
 
 ### Update README.md and build badges