Update release docs

Signed-off-by: smoshiur1237 <[email protected]>

Author: smoshiur1237

.github/ISSUE_TEMPLATE/new_release.md

@@ -14,12 +14,12 @@ For details, see [RELEASE.md](https://github.com/kubernetes-sigs/cluster-api-pro
 - [ ] [When bumping `X` or `Y`] Add a new entry of new release branch to [depandabot.yml](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/.github/dependabot.yml).
 - [ ] [When bumping `X` or `Y`] Add a new entry of new release branch to [security-scan.yaml](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/.github/workflows/security-scan.yaml).
 - [ ] [When bumping `X` or `Y`] Add a new entry to [metadata.yaml](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/metadata.yaml)
-  as [described in the CAPI book](https://cluster-api.sigs.k8s.io/clusterctl/provider-contract.html#metadata-yaml)
+  as [described in the CAPI book](https://cluster-api.sigs.k8s.io/developer/providers/contracts/clusterctl#metadata-yaml)
   on the release branch prior to release.
-- [ ] Push tag to the repository.
+- [ ] Create the PR after generating release notes according to [RELEASE.md](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/RELEASE.md). Verify that the release PR looks good and make changes if necessary. When this PR got merged, release automation will push the tag to upstream and will add the draft release notes.
 - [ ] Promote the [staging image](https://console.cloud.google.com/cloud-build/builds?project=k8s-staging-capi-openstack) by
   adding the new sha=>tag mapping to [images.yaml](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-capi-openstack/images.yaml).
-- [ ] Verify that the new draft release looks good and make changes if necessary.
+- [ ] Verify that the new draft release looks good.
 - [ ] Verify that the image was promoted sucessfully.
 - [ ] Publish the release.
   Mark the release as "latest" if it is the most recent minor release.

RELEASE.md

@@ -41,36 +41,70 @@ The content of the release notes differs depending on the type of release, speci
 There is an [issue template](.github/ISSUE_TEMPLATE/new_release.md) to help track release activities.
 
 1. Make sure your repo is clean by git's standards. It is recommended to use a fresh checkout.
-1. When bumping `X` or `Y` (but not Z or the pre-release suffix) in the release version you must create a new release branch called `release-X.Y`.
-   > NOTE: `upstream` should be the name of the remote pointing to `github.com/kubernetes-sigs/cluster-api-provider-openstack`
-    - `git checkout main`
-    - `git pull`
-    - `git checkout -b release-X.Y`
-    - `git push --set-upstream upstream`
+1. Repository Setup
+   - Clone the repository: `git clone [email protected]:kubernetes-sigs/cluster-api-provider-openstack.git`
+   or if using existing repository, make sure origin is set to the fork and
+   upstream is set to `kubernetes-sigs`. Verify if your remote is set properly or not
+   by using following command `git remote -v`.
+   - Fetch the remote (`kubernetes-sigs`): `git fetch upstream`
+   This makes sure that all the tags are accessible.
+
 1. When bumping `X` or `Y` (but not Z or the pre-release suffix) in the release version, ensure you have added a new
    entry to [metadata.yaml](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/metadata.yaml)
-   as [described in the CAPI book](https://cluster-api.sigs.k8s.io/clusterctl/provider-contract.html#metadata-yaml), and
+   as [described in the CAPI book](https://cluster-api.sigs.k8s.io/developer/providers/contracts/clusterctl#metadata-yaml), and
    that this has been committed to the release branch prior to release.
-1. Make sure you are on the correct release branch: `release-X.Y`
-1. Set an environment variable with the version, e.g.:
-    - `VERSION=v0.6.0`
-1. Create an annotated tag
-    - `git tag -s -a $VERSION -m $VERSION`.
-1. Push the tag to the GitHub repository:
-   > NOTE: `upstream` should be the name of the remote pointing to `github.com/kubernetes-sigs/cluster-api-provider-openstack`
-    - `git push upstream $VERSION`
-
-   This will cause the image to be automatically built by CI and pushed to the staging repository. As this only builds
-   the image, it only takes a few minutes.
-   It also triggers the [release](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/.github/workflows/release.yaml) workflow which will generate release notes and artifacts, and create a draft release in GitHub.
-1. Follow the [image promotion process](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/README.md#image-promoter) to promote the image from the staging repo to `registry.k8s.io/capi-openstack`.
-   The staging repository can be inspected at https://console.cloud.google.com/gcr/images/k8s-staging-capi-openstack/GLOBAL. Be
+
+1. Creating Release Notes
+   - Switch to the main branch: `git checkout main`
+   - Create a new branch for the release notes**:
+     `git checkout -b release-notes-X.Y.Z origin/main`
+   - Generate the release notes: `RELEASE_TAG=vX.Y.Z make generate-release-notes`
+   - Replace `vX.Y.Z` with the new release tag you're creating.
+   - This command generates the release notes here
+     `releasenotes/<RELEASE_TAG>.md` .
+
+1. Next step is to clean up the release note manually.
+   - If release is not an alpha or 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 revertion) 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.
+   - Commit your changes, push the new branch and create a pull request:
+     - The commit and PR title should be 🚀 Release v1.x.y:
+       -`git commit -S -s -m ":rocket: Release vX.Y.Z"`
+       -`git push -u origin release-notes-X.Y.Z`
+     - Important! The commit should only contain the release notes file, nothing
+     else, otherwise automation will not work.
+   - Ask maintainers and release team members to review your pull request.
+
+   Once PR is merged following GitHub actions are triggered:
+
+   - GitHub action `Create Release` runs following jobs
+     - GitHub job `push_release_tags` will create and push the tags. This action
+     will also create release branch if its missing and release is `rc` or minor.
+     - GitHub job `create draft release` creates draft release. Don't publish the
+     release until release tag is visible in. Running actions are visible on the
+      [Actions](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/actions)
+      page, and draft release will be visible on top of the
+      [Releases](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/releases).
+      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 or an alpha
+      release, tick pre-release box.
+
+      This will cause the image to be automatically built by CI and pushed to the staging repository. As this only builds the image, it only takes a few minutes. It also triggers the [release](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/.github/workflows/release.yaml) workflow which will generate release notes and artifacts, and create a draft release in GitHub.
+
+1. Follow the [image promotion process](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/README.md#image-promoter) to promote the image from   the staging repo to `registry.k8s.io/capi-openstack`.
+   The staging repository can be inspected at [Staging CAPI Openstack](https://console.cloud.google.com/gcr/images/k8s-staging-capi-openstack/GLOBAL). Be
    sure to choose the top level `capi-openstack-controller`, which will provide the multi-arch manifest, rather than one for a specific architecture.
    The image build logs are available at [Cloud Build](https://console.cloud.google.com/cloud-build/builds?project=k8s-staging-capi-openstack).
    Add the new sha=>tag mapping to the [images.yaml](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-capi-openstack/images.yaml) (use the sha of the image with the corresponding tag). The PR to update the [images.yaml](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-capi-openstack/images.yaml) must be approved in the [OWNERS](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/images/k8s-staging-capi-openstack/OWNERS) file and merged.
 
-   It is good practise to get somebody else to review this PR. It is safe to perform the following steps while waiting
-   for review and the promotion of the image.
+   It is good practise to get somebody else to review this PR. It is safe to perform the following steps while waiting for review and the promotion of the image.
+
 1. Check carefully the [draft release](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/releases)
    created by the workflow. Ensure that the release notes are correct and that the artifacts are present.
    If any changes are needed, edit the release notes in the GitHub UI and add any missing artifacts.
@@ -96,5 +130,5 @@ Releasing requires a particular set of permissions.
 
 There is a post-submit Prow job running after each commit on `main` which pushes a new image to the staging repo (`gcr.io/k8s-staging-capi-openstack/capi-openstack-controller:latest`). Following configuration is involved:
 * staging gcr bucket: [kubernetes/k8s.io/blob/main/registry.k8s.io/manifests/k8s-staging-capi-openstack/promoter-manifest.yaml](https://github.com/kubernetes/k8s.io/blob/main/registry.k8s.io/manifests/k8s-staging-capi-openstack/promoter-manifest.yaml)
-* post-submit `post-capi-openstack-push-images` Prow job: [kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-cluster-api.yaml](https://github.com/kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-cluster-api.yaml)) (corresponding dashboard is located at [https://testgrid.k8s.io/sig-cluster-lifecycle-image-pushes#post-capi-openstack-push-images](https://testgrid.k8s.io/sig-cluster-lifecycle-image-pushes#post-capi-openstack-push-images))
+* post-submit `post-capi-openstack-push-images` Prow job: [kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-cluster-api.yaml](https://github.com/kubernetes/test-infra/blob/master/config/jobs/image-pushing/k8s-staging-cluster-api.yaml) (corresponding dashboard is located at [https://testgrid.k8s.io/sig-cluster-lifecycle-image-pushes#post-capi-openstack-push-images](https://testgrid.k8s.io/sig-cluster-lifecycle-image-pushes#post-capi-openstack-push-images))
 * Google Cloud Build configuration which is used by the Prow job: [kubernetes-sigs/cluster-api-provider-openstack/cloudbuild.yaml](https://github.com/kubernetes-sigs/cluster-api-provider-openstack/blob/main/cloudbuild.yaml)