Merge pull request #392 from Fedosin/docs_release

📖 Update release docs

Author: k8s-ci-robot

docs/release.md

@@ -1,8 +1,8 @@
-# Releasing new versions
+# Releasing New Versions
 
-This documents describes release process for the Cluster API Operator.
+This document describes the release process for the Cluster API Operator.
 
-1. Create the release branch and cut release tag.
+1. Create a new release branch and cut a release tag.
 
 ```bash
 git checkout -b release-0.1
@@ -24,35 +24,34 @@ git push upstream ${RELEASE_TAG}
 git push upstream test/${RELEASE_TAG}
 ```
 
-This will trigger [release github action](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/.github/workflows/release.yaml) that will
-create a draft release with operator components and helm chart, also a Prow job to publish operator image to the staging registry will start.
+**Note:** You may encounter an ioctl error during tagging. To resolve this, you need to set the GPG_TTY environment variable as `export GPG_TTY=$(tty)`.
 
-2. Wait for image to appear in the [staging registry](https://console.cloud.google.com/gcr/images/k8s-staging-capi-operator/global/cluster-api-operator).
+This will trigger a [release GitHub action](https://github.com/kubernetes-sigs/cluster-api-operator/blob/main/.github/workflows/release.yaml) that creates a release with operator components and the Helm chart. Concurrently, a Prow job will start to publish operator images to the staging registry.
 
-3. Create a GitHub [Personal access tokens](https://github.com/settings/tokens) if you don't have one already. We're going to use for opening a PR
-to promote image from staging to production.
+2. Wait for the images to appear in the [staging registry](https://console.cloud.google.com/gcr/images/k8s-staging-capi-operator/global/cluster-api-operator).
+
+3. Create a GitHub [Personal access token](https://github.com/settings/tokens) if you don't already have one. We're going to use this for opening a PR to promote the images from staging to production.
 
 ```bash
 export GITHUB_TOKEN=<your GH token>
+export USER_FORK=<your GH account name>
 make promote-images
 ```
 
-Merge the PR after it was created and verify that image is present in the production registry.
+After it has been tested, merge the PR and verify that the image is present in the production registry.
 
 ```bash
 docker pull registry.k8s.io/capi-operator/cluster-api-operator:${RELEASE_TAG}
 ```
 
-4. Publish the release on Github.
-
-5. After release was published, switch back to main branch and update index.yaml and clusterctl-operator.yaml. It's the source for operator helm chart repository and local krew plugin manifest index.
+4. Switch back to the main branch and update `index.yaml` and `clusterctl-operator.yaml`. These are the sources for the operator Helm chart repository and the local krew plugin manifest index, respectively.
 
 ```bash
 git checkout main
 make update-helm-plugin-repo
 ```
 
-6. Create a PR with the changes.
+5. Create a PR with the changes.
 
 ## Setup jobs and dashboards for a new release branch