From 807579db7aff793585d1870aa814eecbaa91a550 Mon Sep 17 00:00:00 2001
From: Ashley Davis <ashley.davis@jetstack.io>
Date: Fri, 19 May 2023 15:16:32 +0100
Subject: [PATCH 01/16] post-release 1.12: update the release process with the
 latest process
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I re-arranged the website PR instructions so that the pre-release steps for the
website are shown first. I also made it clearer that we produce two types of
release notes: the GitHub release description and the "Release Note" page on the
website.

- Mention "How we determine supported Kubernetes".
- Mention how to transform GitHub references into links in the
  `release-notes.md` file.
- Mention bump 1.12 in generate-new-import-path-docs
- Mention the freeze of docs/ that gets copied into v1.12-docs/.
- Mention how to bump the gen scripts.
- Show a command that to bump versions in install instructions.
- Mention manifest.json that needs to be updated.
- Mention the file release-notes/README.md's index that needs updating.

I also had to re-order the bullet points due to conflicts with Irbe's changes to
the release process document. Apologies for the noise that these changes
introduce!

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 213 ++++++++++++-------
 1 file changed, 136 insertions(+), 77 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 248c640de0..cc4e008a98 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -141,7 +141,7 @@ page if a step is missing or if it is outdated.
     | (optional) patch pre-release[^1]   | `v1.3.1-beta.0`    |
     | patch release (or "point release") | `v1.3.1`           |
 
-[^1]: One or more "patch pre-releases" may be created to allow voluntary community testing of a bug fix or security fix before the fix is made generally available. The suffix `-beta` must be used for patch pre-releases.
+   [^1]: One or more "patch pre-releases" may be created to allow voluntary community testing of a bug fix or security fix before the fix is made generally available. The suffix `-beta` must be used for patch pre-releases.
 
 2. **(final release only)** Make sure that a PR with the new upgrade
    document is ready to be merged on
@@ -149,7 +149,103 @@ page if a step is missing or if it is outdated.
    example, see
    [upgrading-1.0-1.1](https://cert-manager.io/docs/installation/upgrading/upgrading-1.0-1.1/).
 
-3. Check that the `origin` remote is correct. To do that, run the following
+3. **(final + patch releases)** **Website Updates, part 1** (creating the "release
+   notes" PR).
+
+     **⚠️ This step can be done ahead of time.**
+
+     The steps below need to happen using `master` (**final release**) or
+     `release-1.x` (**patch release**). The PR will be merged after the release.
+
+   1. Go to the Generate `release-notes.md` using the instructions further below
+     (<kbd>Ctrl+F</kbd> and look for `github-release-description.md`).
+   2. Remove the "Dependencies" section.
+   3. Edit any `release-note` block in the PR description that doesn't follow
+      the [release-note guidelines](../contributing/contributing-flow.md#release-note-guidelines)
+      and copy the same change into `release-notes.md` (or re-generate the
+      file).
+   4. Add the section "Major themes" and "Community" by taking example on the
+     previous release note pages.
+   5. Replace the GitHub issue numbers and GitHub handles (e.g., `#1234` or
+       `@maelvls`) with actual links using the following command:
+
+       ```bash
+       sed github-release-description.md \
+         -e 's$#([0-9]+)$[#\1](https://github.com/cert-manager/cert-manager/pull/\1)$g' \
+         -e 's$@(\w+)$[@\1](https://github.com/\1)$g' \
+         -E \
+         -i
+       ```
+
+   6. Move `release-notes.md` to the website repo:
+
+      ```bash
+      # From the cert-manager repo.
+      mv release-notes.md ../website/content/docs/release-notes-1.X.md
+      ```
+
+   7. Add an entry to `content/docs/manifest.json`:
+
+        ```diff
+         {
+           "title": "Release Notes",
+           "routes": [
+        +    {
+        +      "title": "v1.12",
+        +      "path": "/docs/release-notes/release-notes-1.12.md"
+        +    },
+        ```
+
+   8. Add a line to the file `content/docs/release-notes/README.md`.
+
+4. **(final + patch release)** Prepare the "website updates" PR for the website.
+
+   > ⚠️ This step can be done ahead of time.
+
+   In that PR:
+
+   1. (**final release**) Update the section "Supported releases" in the
+     [supported-releases](../installation/supported-releases.md) page.
+   2. (**final release**) Update the section "How we determine supported
+     Kubernetes versions" on the
+     [supported-releases](../installation/supported-releases.md) page.
+   3. (**final release**) Bump the version that appears in
+     `scripts/gendocs/generate-new-import-path-docs`. For example:
+      ```diff
+      -LATEST_VERSION="v1.11-docs"
+      +LATEST_VERSION="v1.12-docs"
+
+      -genversionwithcli "release-1.11" "$LATEST_VERSION"
+      +genversionwithcli "release-1.12" "$LATEST_VERSION"
+      ```
+
+   4. (**final + patch release**) Bump all versions present in installation
+     instructions. To find these versions:
+
+      ```bash
+      find ./content/docs/installation -name '*.md' -not -path '*/upgrad**' -exec sed -i.bak 's/1.11../1.12.0/g' '{}' \;
+      rm -f **/*.bak
+      ```
+
+      To check that all mentions of that versions are gone, run:
+
+      ```bash
+      grep -R -n -F 'v1.11.' content/docs/installation
+      ```
+
+   5. (**final release only**) Freeze the `docs/` folder by creating a copy
+     and remove the `docs/`-only folders:
+      ```bash
+      cp -r content/docs content/v1.12-docs
+      rm -rf content/v1.12-docs/{installation/supported-releases,installation/upgrading,release-notes}
+      ```
+   6. (**final + patch releases**) Update the [API docs](https://cert-manager.io/docs/reference/api-docs/) and [CLI docs](https://cert-manager.io/docs/cli//):
+      ```bash
+      # From the website repository, on the master branch.
+      ./scripts/gendocs/generate
+      ```
+
+5. Check that the `origin` remote is correct. To do that, run the following
    command and make sure it returns the upstream
    `https://github.com/cert-manager/cert-manager.git`:
 
@@ -165,7 +261,7 @@ page if a step is missing or if it is outdated.
     origin  https://github.com/jetstack/cert-manager (push)
     ```
 
-4. Place yourself on the correct branch:
+6. Place yourself on the correct branch:
 
    - **(initial alpha and subsequent alpha)**: place yourself on the `master`
      branch:
@@ -192,7 +288,7 @@ page if a step is missing or if it is outdated.
       permission, you will have to open a PR to merge master into the release
       branch), and wait for the PR checks to become green.
 
-    - **(subsequent beta, patch release and final release)**: place yourself on
+   - **(subsequent beta, patch release and final release)**: place yourself on
       the release branch:
 
       ```bash
@@ -225,7 +321,7 @@ page if a step is missing or if it is outdated.
    >  This is only a temporary change to allow you to update the branch.
    >  [Prow will re-apply the branch protection within 24 hours](https://docs.prow.k8s.io/docs/components/optional/branchprotector/#updating).
 
-5. Create the required tags for the new release locally and push it upstream (starting the cert-manager build):
+7. Create the required tags for the new release locally and push it upstream (starting the cert-manager build):
 
      ```bash
      RELEASE_VERSION=v1.8.0-beta.0
@@ -244,11 +340,12 @@ page if a step is missing or if it is outdated.
       kicking off a build using the steps in `gcb/build_cert_manager.yaml`. Users with access to
       the cert-manager-release project on GCP should be able to view logs in [GCB build history](https://console.cloud.google.com/cloud-build/builds?project=cert-manager-release).
 
-6. Ensure that cmctl refers to the latest tag of cert-manager:
+8. Ensure that cmctl refers to the latest tag of cert-manager:
+
+   1. Bump cert-manager version in [cmctl `go.mod` file](https://github.com/cert-manager/cert-manager/blob/v1.12.0/cmd/ctl/go.mod#L15) and cherry-pick the commit to the release branch.
 
-Bump cert-manager version in [cmctl `go.mod` file](https://github.com/cert-manager/cert-manager/blob/v1.12.0/cmd/ctl/go.mod#L15) and cherry-pick the commit to the release branch.
+   2. Add the tag for cmctl:
 
-Add the tag for cmctl:
      ```bash
      # This tag is required to be able to go install cmctl
      # See https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
@@ -256,7 +353,11 @@ Add the tag for cmctl:
      git push origin "cmd/ctl/$RELEASE_VERSION"
      ```
 
-7. Generate and edit the release notes:
+9. Create the description for the GitHub Release:
+
+    > **Note:** This step is about creating the description that will be
+    > copy-pasted into the GitHub release page. The creation of the "Release
+    > Note" page on the website is done in a previous step.
 
     1. Use the following two tables to understand how to fill in the four
        environment variables needed for the next step. These four environment
@@ -301,8 +402,7 @@ Add the tag for cmctl:
         export BRANCH="release-1.3"
         ```
 
-    2. Generate `release-notes.md` at the root of your cert-manager repo folder
-       with the following command:
+    2. Generate `github-release-description.md` with the following command:
 
         ```bash
         # Must be run from the cert-manager folder.
@@ -312,33 +412,19 @@ Add the tag for cmctl:
         release-notes --debug --repo-path cert-manager \
           --org cert-manager --repo cert-manager \
           --required-author "jetstack-bot" \
-          --output release-notes.md
+          --output github-release-description.md
         ```
 
         <div className="pageinfo pageinfo-info"><p>
         The GitHub token **does not need any scope**. The token is required
         only to avoid rate-limits imposed on anonymous API users.
         </p></div>
+    3. Add a one-sentence summary at the top.
 
-    3. Sanity check the notes:
-
-        - Make sure the notes contain details of all the features and bug
-          fixes that you expect to be in the release.
-        - Add additional blurb, notable items and characterize change log.
-
-        You can see the commits that will go into this release by using the
-        [GitHub compare](https://github.com/cert-manager/cert-manager/compare). For
-        example, while releasing `v1.0.0`, you want to compare it with the
-        latest pre-released version `v1.0.0-beta.1`:
-
-        ```text
-        https://github.com/cert-manager/cert-manager/compare/v1.0.0-beta.1...master
-        ```
+    4. **(final release only)** Write the section "Community" by taking example
+       on past GitHub Releases.
 
-    4. **(final release only)** Check the release notes include all changes
-       since the last final release.
-
-8. Check that the build is complete and send Slack messages about the release:
+10. Check that the build is complete and send Slack messages about the release:
 
     1. For recent versions of cert-manager, the build will have been automatically
        triggered by the tag being pushed earlier. You can check if it's complete on
@@ -370,14 +456,14 @@ Add the tag for cmctl:
         properly redacted but sometimes we forget to update this.
         </p></div>
 
-    3. Send a second Slack message in reply to this first message with the
+    4. Send a second Slack message in reply to this first message with the
        Cloud Build job link. For example, the message might look like:
 
         <div className="pageinfo pageinfo-info"><p>
         Follow the <code>cmrel makestage</code> build: https://console.cloud.google.com/cloud-build/builds/7641734d-fc3c-42e7-9e4c-85bfc4d1d547?project=1021342095237
         </p></div>
 
-9. Run `cmrel publish`:
+11. Run `cmrel publish`:
 
     1. Do a `cmrel publish` dry-run to ensure that all the staged resources are
        valid. Run the following command:
@@ -422,7 +508,7 @@ Add the tag for cmctl:
         Follow the <code>cmrel publish</code> build: https://console.cloud.google.com/cloud-build/builds/b6fef12b-2e81-4486-9f1f-d00592351789?project=1021342095237
         </p></div>
 
-10. Publish the GitHub release:
+12. Publish the GitHub release:
 
     1. Visit the draft GitHub release and paste in the release notes that you
        generated earlier. You will need to manually edit the content to match
@@ -437,11 +523,11 @@ Add the tag for cmctl:
 
     4. Click "Publish" to make the GitHub release live.
 
-11. Merge the pull request containing the Helm chart:
+13. Merge the pull request containing the Helm chart:
 
-   The Helm charts for cert-manager are served using Cloudflare pages
-   and the Helm chart files and metadata are stored in the [Jetstack charts repository](https://github.com/jetstack/jetstack-charts).
-   The `cmrel publish --nomock` step (above) will have created a PR in this repository which you now have to review and merge, as follows:
+    The Helm charts for cert-manager are served using Cloudflare pages
+    and the Helm chart files and metadata are stored in the [Jetstack charts repository](https://github.com/jetstack/jetstack-charts).
+    The `cmrel publish --nomock` step (above) will have created a PR in this repository which you now have to review and merge, as follows:
 
     1. [Visit the pull request](https://github.com/jetstack/jetstack-charts/pulls)
     2. Review the changes
@@ -449,10 +535,12 @@ Add the tag for cmctl:
     4. Merge the PR
     5. Check that the [cert-manager Helm chart is visible on ArtifactHUB](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
 
-12. **(final release only)** Add the new final release to the
-    [supported-releases](../installation/supported-releases.md) page.
+14. **(final + patch releases)** **Website Updates, part 2.**
+
+    Proceed with merging the website PRs "release notes" and "website bump" you
+    have created previously.
 
-13. Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
+15. Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
 
     Assuming you have `brew` installed, you can use the `brew bump-formula-pr`
     command to do this. You'll need the new tag name and the commit hash of that
@@ -469,7 +557,7 @@ Add the tag for cmctl:
     against https://github.com/homebrew/homebrew-core has been opened, continue
     with further release steps.
 
-14. Post a Slack message as an answer to the first message. Toggle the check
+16. Post a Slack message as an answer to the first message. Toggle the check
    box "Also send to `#cert-manager-dev`" so that the message is well
    visible. Also cross-post the message on `#cert-manager`.
 
@@ -477,7 +565,7 @@ Add the tag for cmctl:
     https://github.com/cert-manager/cert-manager/releases/tag/v1.0.0 🎉
     </p></div>
 
-15. **(final release only)** Show the release to the world:
+17. **(final release only)** Show the release to the world:
 
     1. Send an email to
        [`cert-manager-dev@googlegroups.com`](https://groups.google.com/g/cert-manager-dev)
@@ -490,7 +578,7 @@ Add the tag for cmctl:
     3. Send a toot from the cert-manager Mastodon account! Login details are in Jetstack's 1password (for now).
        ([Example toot](https://infosec.exchange/@CertManager/109666434738850493))
 
-16. Proceed to the post-release steps:
+18. Proceed to the post-release "testing and release" steps:
 
     1. **(initial beta only)** Create a PR on
        [cert-manager/release](https://github.com/cert-manager/release) in order to
@@ -500,15 +588,7 @@ Add the tag for cmctl:
        open a PR to [cert-manager/testing](https://github.com/jetstack/testing) adding the generated prow configs.
        Use [this PR](https://github.com/jetstack/testing/pull/766) as an example.
 
-    3. If needed, open a PR to
-       [`cert-manager/website`](https://github.com/cert-manager/website) in
-       order to:
-
-       - Update the section "How we determine supported Kubernetes versions" on
-         the [supported-releases](../installation/supported-releases.md) page.
-       - Add any new release notes, if needed.
-
-    4. **(final release only)** Create a PR on
+    3. **(final release only)** Create a PR on
        [cert-manager/release](https://github.com/cert-manager/release),
        removing the now unsupported release version (2 versions back) in this file:
 
@@ -518,10 +598,10 @@ Add the tag for cmctl:
 
        This will remove the periodic ProwJobs for this version as they're no longer needed.
 
-    5. **(final release only)** Run `cmrel generate-prow --branch='*' -o file` with the new version from the previous step and
+    4. **(final release only)** Run `cmrel generate-prow --branch='*' -o file` with the new version from the previous step and
        open a PR to [jetstack/testing](https://github.com/jetstack/testing) adding the generated prow configs.
 
-    6. **(final release only)** Open a PR to [`jetstack/testing`](https://github.com/jetstack/testing)
+    5. **(final release only)** Open a PR to [`jetstack/testing`](https://github.com/jetstack/testing)
        and update the [milestone_applier](https://github.com/jetstack/testing/blob/3110b68e082c3625bf0d26265be2d29e41da14b2/config/plugins.yaml#L69)
        config so that newly raised PRs on master are applied to a new milestone
        for the next release. E.g. if master currently points at the `v1.10` milestone, change it to point at `v1.11`.
@@ -529,32 +609,11 @@ Add the tag for cmctl:
        If the [milestone](https://github.com/cert-manager/cert-manager/milestones) for the next release doesn't exist,
        create it first. If you consider the milestone for the version you just released to be complete, close it.
 
-    7. **(final release only)** Open a PR to
-       [`cert-manager/website`](https://github.com/cert-manager/website) in
-       order to:
-
-       - Update the section "Supported releases" in the
-         [supported-releases](../installation/supported-releases.md) page.
-       - Update the section "How we determine supported Kubernetes versions" on
-         the [supported-releases](../installation/supported-releases.md) page.
-         In the table, set "n/a" for the line where "next periodic" is since
-         these tests will be disabled until we do our first alpha.
-       - Update the [API docs](../reference/api-docs.md) and [CLI docs](../cli/README.md) by running `scripts/gendocs/generate`
-         and commit any changes to a branch and create a PR to merge those into
-         `master` or `release-next` depending on whether this is a minor or
-         patch release.
-
-    8. Ensure that any installation commands in
-       [`cert-manager/website`](https://github.com/cert-manager/website) install
-       the latest version. This should be done after every release, including
-       patch releases as we want to encourage users to always install the latest
-       patch. In addition, ensure that release notes for the latest version are added.
-
-    9. Open a PR against the Krew index such as [this one](https://github.com/kubernetes-sigs/krew-index/pull/1724),
+    6. Open a PR against the Krew index such as [this one](https://github.com/kubernetes-sigs/krew-index/pull/1724),
       bumping the versions of our kubectl plugins. This is likely only worthwhile if
       cmctl / kubectl plugin functionality has changed significantly or after the first release of a new major version.
 
-    10. Create a new OLM package and publish to OperatorHub
+    7. Create a new OLM package and publish to OperatorHub
 
        cert-manager can be [installed](https://cert-manager.io/docs/installation/operator-lifecycle-manager/) using Operator Lifecycle Manager (OLM)
        so we need to create OLM packages for each cert-manager version and publish them to both

From dd07552e00264ea50a0a75bdeab3ddcdb7b6eb5c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 23 May 2023 12:38:35 +0200
Subject: [PATCH 02/16] release-process: explain how to merge release-next into
 master
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 32 +++++++++++++++-----
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index cc4e008a98..bd5f33709f 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -143,14 +143,15 @@ page if a step is missing or if it is outdated.
 
    [^1]: One or more "patch pre-releases" may be created to allow voluntary community testing of a bug fix or security fix before the fix is made generally available. The suffix `-beta` must be used for patch pre-releases.
 
-2. **(final release only)** Make sure that a PR with the new upgrade
+2. **(final release only)** Prepare the Website "Upgrade Notes" PR.
+
+   Make sure that a PR with the new upgrade
    document is ready to be merged on
    [cert-manager/website](https://github.com/cert-manager/website). See for
    example, see
    [upgrading-1.0-1.1](https://cert-manager.io/docs/installation/upgrading/upgrading-1.0-1.1/).
 
-3. **(final + patch releases)** **Website Updates, part 1** (creating the "release
-   notes" PR).
+3. **(final + patch releases)** Prepare the Website "Release Notes" PR.
 
      **⚠️ This step can be done ahead of time.**
 
@@ -198,7 +199,7 @@ page if a step is missing or if it is outdated.
 
    8. Add a line to the file `content/docs/release-notes/README.md`.
 
-4. **(final + patch release)** Prepare the "website updates" PR for the website.
+4. **(final + patch release)** Prepare the Website "Release Notes" PR.
 
    > ⚠️ This step can be done ahead of time.
 
@@ -211,6 +212,7 @@ page if a step is missing or if it is outdated.
      [supported-releases](../installation/supported-releases.md) page.
    3. (**final release**) Bump the version that appears in
      `scripts/gendocs/generate-new-import-path-docs`. For example:
+
       ```diff
       -LATEST_VERSION="v1.11-docs"
       +LATEST_VERSION="v1.12-docs"
@@ -235,11 +237,14 @@ page if a step is missing or if it is outdated.
 
    5. (**final release only**) Freeze the `docs/` folder by creating a copy
      and remove the `docs/`-only folders:
+
       ```bash
       cp -r content/docs content/v1.12-docs
       rm -rf content/v1.12-docs/{installation/supported-releases,installation/upgrading,release-notes}
       ```
+
    6. (**final + patch releases**) Update the [API docs](https://cert-manager.io/docs/reference/api-docs/) and [CLI docs](https://cert-manager.io/docs/cli//):
+
       ```bash
       # From the website repository, on the master branch.
       ./scripts/gendocs/generate
@@ -535,10 +540,23 @@ page if a step is missing or if it is outdated.
     4. Merge the PR
     5. Check that the [cert-manager Helm chart is visible on ArtifactHUB](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
 
-14. **(final + patch releases)** **Website Updates, part 2.**
+14. **(final + patch releases)** Merge the 4 Website PRs:
+
+    1. Merge the PRs "Release Notes", "Upgrade Notes", and "Freeze And Bump
+       Versions" that you have created previously.
+    2. Create the PR "Merge release-next into master" by [clicking
+       here][ff-release-next].
+
+       If you see the label `dco-signoff: no`, add a comment on the PR with:
+
+       ```text
+       /override dco
+       ```
+
+       This command is necessary because some the merge commits have been
+       written by the bot and do not have a DCO signoff.
 
-    Proceed with merging the website PRs "release notes" and "website bump" you
-    have created previously.
+      [ff-release-next]: https://github.com/cert-manager/website/compare/master...release-next?quick_pull=1&title=%5BPost-Release%5D+Merge+release-next+into+master&body=%3C%21--%0A%0AThe+command+%22%2Foverride+dco%22+is+necessary+because+some+the+merge+commits%0Ahave+been+written+by+the+bot+and+do+not+have+a+DCO+signoff.%0A%0A--%3E%0A%0A%2Foverride+dco
 
 15. Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
 

From 0ba7b052412686f1ea0cac7cb0bc25190abe6fb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Mon, 27 Feb 2023 17:13:54 +0100
Subject: [PATCH 03/16] package.json: use "npm exec" for running the
 "concurrently" tool
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 55a5892a89..40ffc6f788 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "generate:sitemap": "next-sitemap",
     "export": "next export",
     "start": "next start",
-    "check": "concurrently --group --timings npm:check:* # Run all the npm check:* scripts in parallel",
+    "check": "npm exec concurrently -y -- --group --timings npm:check:* # Run all the npm check:* scripts in parallel",
     "check:next-lint": "next lint",
     "check:links": "find content/docs -type f -name '*.md' | xargs markdown-link-check --quiet --config markdown-link-check.json 2>&1 | awk -v RS=FILE: '/ERROR/{f=1; print RS $0} END{exit f}' # Split into records based on the word FILE and print only records containing word ERROR",
     "check:spelling": "FORCE_COLOR=1 mdspell --report --en-us --ignore-numbers --ignore-acronyms 'content/**/*.md' 'content/**/*.html' '_layouts/*.html' '_includes/*.html' '*.html' '!**/api-docs.md' '!content/*docs/projects/approver-policy/api-reference.md' # Force color output in mdspell. # See https://github.com/lukeapage/node-markdown-spellcheck/issues/36#issuecomment-482649408 ",

From e0c2085c37eb575f350d22ed52a5257628c50b55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 7 Mar 2023 10:32:57 +0100
Subject: [PATCH 04/16] Revert "package.json: use "npm exec" for running the
 "concurrently" tool"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This reverts commit c399aae52becfd2780a909ce2d62e8182ad91f01.

I mistakenly forgot to run "npm i" before running ./scripts/verify.

Signed-off-by: Maël Valais <mael@vls.dev>
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 40ffc6f788..55a5892a89 100644
--- a/package.json
+++ b/package.json
@@ -22,7 +22,7 @@
     "generate:sitemap": "next-sitemap",
     "export": "next export",
     "start": "next start",
-    "check": "npm exec concurrently -y -- --group --timings npm:check:* # Run all the npm check:* scripts in parallel",
+    "check": "concurrently --group --timings npm:check:* # Run all the npm check:* scripts in parallel",
     "check:next-lint": "next lint",
     "check:links": "find content/docs -type f -name '*.md' | xargs markdown-link-check --quiet --config markdown-link-check.json 2>&1 | awk -v RS=FILE: '/ERROR/{f=1; print RS $0} END{exit f}' # Split into records based on the word FILE and print only records containing word ERROR",
     "check:spelling": "FORCE_COLOR=1 mdspell --report --en-us --ignore-numbers --ignore-acronyms 'content/**/*.md' 'content/**/*.html' '_layouts/*.html' '_includes/*.html' '*.html' '!**/api-docs.md' '!content/*docs/projects/approver-policy/api-reference.md' # Force color output in mdspell. # See https://github.com/lukeapage/node-markdown-spellcheck/issues/36#issuecomment-482649408 ",

From 7491a300cbb5063b33f4748079cf3f94b534eabd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Mon, 19 Jun 2023 18:38:05 +0200
Subject: [PATCH 05/16] release-process: explain /docs -> /v1.12-docs in
 manifest.json
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 .gitignore                                   | 5 ++++-
 content/docs/contributing/release-process.md | 6 ++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index cb88a5aa38..51b489a0e5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,4 +49,7 @@ public/feed.*
 .netlify/
 
 # IntelliJ
-.idea
\ No newline at end of file
+.idea
+
+# Our release-process.md tells us to run 'sed' commands that create .bak files.
+*.bak
diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index bd5f33709f..e2b055a156 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -235,12 +235,14 @@ page if a step is missing or if it is outdated.
       grep -R -n -F 'v1.11.' content/docs/installation
       ```
 
-   5. (**final release only**) Freeze the `docs/` folder by creating a copy
-     and remove the `docs/`-only folders:
+   5. (**final release only**) Freeze the `docs/` folder by creating a copy ,
+     removing the pages from that copy that don't make sense to be versionned,
+     and updating the `manifest.json` file:
 
       ```bash
       cp -r content/docs content/v1.12-docs
       rm -rf content/v1.12-docs/{installation/supported-releases,installation/upgrading,release-notes}
+      sed -i.bak 's|docs|v1.12-docs|g' content/v1.12-docs/manifest.json
       ```
 
    6. (**final + patch releases**) Update the [API docs](https://cert-manager.io/docs/reference/api-docs/) and [CLI docs](https://cert-manager.io/docs/cli//):

From 8690cf7246cee5563c22bf06e3a53a3bfaaa6775 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Mon, 19 Jun 2023 18:48:49 +0200
Subject: [PATCH 06/16] release-process: typo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index e2b055a156..162076c63e 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -236,7 +236,7 @@ page if a step is missing or if it is outdated.
       ```
 
    5. (**final release only**) Freeze the `docs/` folder by creating a copy ,
-     removing the pages from that copy that don't make sense to be versionned,
+     removing the pages from that copy that don't make sense to be versioned,
      and updating the `manifest.json` file:
 
       ```bash

From f1a7ed92f92c65d595f0ef98f84e088e5696ea31 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 17:22:56 +0200
Subject: [PATCH 07/16] release-process: explain how to properly update the
 manifest.json
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 .spelling                                    | 1 +
 content/docs/contributing/release-process.md | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/.spelling b/.spelling
index 3580cb7ec8..3d0a6b35e2 100644
--- a/.spelling
+++ b/.spelling
@@ -255,6 +255,7 @@ VPC
 VaaS
 Velero
 Venafi
+versioned
 WebhookConfiguration
 WIP
 YAML
diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 162076c63e..0694ebd5b8 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -243,6 +243,8 @@ page if a step is missing or if it is outdated.
       cp -r content/docs content/v1.12-docs
       rm -rf content/v1.12-docs/{installation/supported-releases,installation/upgrading,release-notes}
       sed -i.bak 's|docs|v1.12-docs|g' content/v1.12-docs/manifest.json
+      jq 'del(.. | select(.path? | select(.) | test(".*(installation/supported-releases.md|installation/upgrading|release-notes).*")))' \
+         content/v1.12-docs/manifest.json >tmp && mv tmp content/v1.12-docs/manifest.json
       ```
 
    6. (**final + patch releases**) Update the [API docs](https://cert-manager.io/docs/reference/api-docs/) and [CLI docs](https://cert-manager.io/docs/cli//):

From b88c5262760af214c86b60921b624be8ec369abf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 18:21:10 +0200
Subject: [PATCH 08/16] release-process: RELASE_VERSION -> RELEASE_VERSION
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 0694ebd5b8..86665482b7 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -355,12 +355,12 @@ page if a step is missing or if it is outdated.
 
    2. Add the tag for cmctl:
 
-     ```bash
-     # This tag is required to be able to go install cmctl
-     # See https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
-     git tag -m"cmd/ctl/$RELEASE_VERSION" "cmd/ctl/$RELASE_VERSION"
-     git push origin "cmd/ctl/$RELEASE_VERSION"
-     ```
+       ```bash
+       # This tag is required to be able to go install cmctl
+       # See https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
+       git tag -m"cmd/ctl/$RELEASE_VERSION" "cmd/ctl/$RELEASE_VERSION"
+       git push origin "cmd/ctl/$RELEASE_VERSION"
+       ```
 
 9. Create the description for the GitHub Release:
 

From 7cb717b7e74b2ad81742059b3738eb929757e99e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 18:41:24 +0200
Subject: [PATCH 09/16] explain how to do the update to the go.mod file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 35 ++++++++++++++------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 86665482b7..e13d4ee39d 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -349,20 +349,35 @@ page if a step is missing or if it is outdated.
       kicking off a build using the steps in `gcb/build_cert_manager.yaml`. Users with access to
       the cert-manager-release project on GCP should be able to view logs in [GCB build history](https://console.cloud.google.com/cloud-build/builds?project=cert-manager-release).
 
-8. Ensure that cmctl refers to the latest tag of cert-manager:
+8. In this step, we make sure the Go module
+   `github.com/cert-manager/cert-manager/cmd/cmctl` can be imported by
+   third-parties.
 
-   1. Bump cert-manager version in [cmctl `go.mod` file](https://github.com/cert-manager/cert-manager/blob/v1.12.0/cmd/ctl/go.mod#L15) and cherry-pick the commit to the release branch.
+    First, update the `cmd/cmctl`'s `go.mod` with the tag we just created:
 
-   2. Add the tag for cmctl:
+     ```bash
+     # Must be run from the cert-manager repo folder.
+     cd cmd/cmctl
+     go get github.com/cert-manager/cert-manager@$RELEASE_VERSION
+     git add go.mod go.sum
+     git commit -m"Update cmd/cmctl's go.mod to $RELEASE_VERSION"
+     cd ../..
+     ```
 
-       ```bash
-       # This tag is required to be able to go install cmctl
-       # See https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
-       git tag -m"cmd/ctl/$RELEASE_VERSION" "cmd/ctl/$RELEASE_VERSION"
-       git push origin "cmd/ctl/$RELEASE_VERSION"
-       ```
+    Then, create a tag for the `cmd/cmctl` module:
+
+     ```bash
+     # Must be run from the cert-manager repo folder.
+     git tag -m"cmd/ctl/$RELEASE_VERSION" "cmd/ctl/$RELEASE_VERSION"
+     git push origin "cmd/ctl/$RELEASE_VERSION"
+     ```
+
+    > **Note:** the reason we need to do this is explained on Stack Overflow:
+    [how-are-versions-of-a-sub-module-managed][]
+
+    [how-are-versions-of-a-sub-module-managed]: https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
 
-9. Create the description for the GitHub Release:
+9. In this section, we will be creating the description for the GitHub Release.
 
     > **Note:** This step is about creating the description that will be
     > copy-pasted into the GitHub release page. The creation of the "Release

From ce38e4c58acab0856fc75871a86ca9cff0f5dc73 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 19:12:47 +0200
Subject: [PATCH 10/16] release-process: let's set the env vars at the start
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 161 +++++++++++--------
 1 file changed, 92 insertions(+), 69 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index e13d4ee39d..173b3010e6 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -128,8 +128,10 @@ some of these goals are missed, in order to keep up release velocity.
 page if a step is missing or if it is outdated.
 </div>
 
-1. Make sure to note which type of release you are doing. That will be helpful
-   in the next steps.
+1. Remind yourself of our release terminology by looking at the following table.
+   This will allow you to know which steps to skip by looking the header of the
+   step, e.g., **(final release only)** means that this step must only be
+   performed when doing a final release.
 
     |          Type of release           | Example of git tag |
     |------------------------------------|--------------------|
@@ -143,7 +145,44 @@ page if a step is missing or if it is outdated.
 
    [^1]: One or more "patch pre-releases" may be created to allow voluntary community testing of a bug fix or security fix before the fix is made generally available. The suffix `-beta` must be used for patch pre-releases.
 
-2. **(final release only)** Prepare the Website "Upgrade Notes" PR.
+2. Set the 4 env variables by copying the following snippet in your shell table:
+
+     ```bash
+     export RELEASE_VERSION="v1.3.0-alpha.0"
+     export START_TAG="v1.2.0"
+     export END_REV="release-1.3"
+     export BRANCH="release-1.3"
+     ```
+
+    > **Note:** To help you fill in the correct values, use the following
+    > examples:
+    >
+    > | Variable          | Example 1        | Example 2        | Example 2        | Example 3     | Example 4     |
+    > | ----------------- | ---------------- | ---------------- | ---------------- | ------------- | ------------- |
+    > |                   | initial alpha    | subsequent alpha | beta release     | final release | patch release |
+    > | `RELEASE_VERSION` | `v1.3.0-alpha.0` | `v1.3.0-alpha.1` | `v1.3.0-beta.0`  | `v1.3.0`      | `v1.3.1`      |
+    > | `START_TAG`       | `v1.2.0`         | `v1.3.0-alpha.0` | `v1.3.0-alpha.1` | `v1.2.0`\*    | `v1.3.0`      |
+    > | `END_REV`         | `master`         | `master`         | `release-1.3`    | `release-1.3` | `release-1.3` |
+    > | `BRANCH`          | `master`         | `master`         | `release-1.3`    | `release-1.3` | `release-1.3` |
+    >
+    > \*Do not use a patch here (e.g., no `v1.2.3`). It must be `v1.2.0`:
+    > you must use the latest tag that belongs to the release branch you are
+    > releasing on; in the above example, the release branch is
+    > `release-1.3`, and the latest tag on that branch is `v1.2.0`.
+
+    > **Note:** The 4 variables are described in [the README of the
+   `release-notes`
+   tool](https://github.com/kubernetes/release/blob/master/cmd/release-notes/README.md#options).
+   For your convenience, the following table summarizes what you need to know:
+    >
+    > | Variable          | Description                             |
+    > | ----------------- | --------------------------------------- |
+    > | `RELEASE_VERSION` | The git tag                             |
+    > | `START_TAG`\*     | The git tag of the "previous"\* release |
+    > | `END_REV`         | Name of your release branch (inclusive) |
+    > | `BRANCH`          | Name of your release branch             |
+
+3. **(final release only)** Prepare the Website "Upgrade Notes" PR.
 
    Make sure that a PR with the new upgrade
    document is ready to be merged on
@@ -151,7 +190,7 @@ page if a step is missing or if it is outdated.
    example, see
    [upgrading-1.0-1.1](https://cert-manager.io/docs/installation/upgrading/upgrading-1.0-1.1/).
 
-3. **(final + patch releases)** Prepare the Website "Release Notes" PR.
+4. **(final + patch releases)** Prepare the Website "Release Notes" PR.
 
      **⚠️ This step can be done ahead of time.**
 
@@ -199,7 +238,7 @@ page if a step is missing or if it is outdated.
 
    8. Add a line to the file `content/docs/release-notes/README.md`.
 
-4. **(final + patch release)** Prepare the Website "Release Notes" PR.
+5. **(final + patch release)** Prepare the Website "Release Notes" PR.
 
    > ⚠️ This step can be done ahead of time.
 
@@ -254,7 +293,7 @@ page if a step is missing or if it is outdated.
       ./scripts/gendocs/generate
       ```
 
-5. Check that the `origin` remote is correct. To do that, run the following
+6. Check that the `origin` remote is correct. To do that, run the following
    command and make sure it returns the upstream
    `https://github.com/cert-manager/cert-manager.git`:
 
@@ -270,7 +309,7 @@ page if a step is missing or if it is outdated.
     origin  https://github.com/jetstack/cert-manager (push)
     ```
 
-6. Place yourself on the correct branch:
+7. Place yourself on the correct branch:
 
    - **(initial alpha and subsequent alpha)**: place yourself on the `master`
      branch:
@@ -330,30 +369,37 @@ page if a step is missing or if it is outdated.
    >  This is only a temporary change to allow you to update the branch.
    >  [Prow will re-apply the branch protection within 24 hours](https://docs.prow.k8s.io/docs/components/optional/branchprotector/#updating).
 
-7. Create the required tags for the new release locally and push it upstream (starting the cert-manager build):
+8. Create the required tags for the new release locally and push it upstream (starting the cert-manager build):
 
      ```bash
-     RELEASE_VERSION=v1.8.0-beta.0
+     echo $RELEASE_VERSION
      git tag -m"$RELEASE_VERSION" $RELEASE_VERSION
      # be sure to push the named tag explicitly; you don't want to push any other local tags!
      git push origin $RELEASE_VERSION
      ```
 
-      **GitHub permissions**: `git push` will only work if you have the
-      `admin` GitHub permission on the cert-manager repo to create or push to
-      the branch, see [prerequisites](#prerequisites). If you do not have this
-      permission, you will have to open a PR to merge master into the release
-      branch), and wait for the PR checks to become green.
+      > **Note**: `git push` will only work if you have the `admin` GitHub
+      > permission on the cert-manager repo to create or push to the branch, see
+      > [prerequisites](#prerequisites). If you do not have this permission, you
+      > will have to open a PR to merge master into the release branch), and
+      > wait for the PR checks to become green.
 
-      For recent versions of cert-manager, the tag being pushed will trigger a Google Cloud Build job to start,
-      kicking off a build using the steps in `gcb/build_cert_manager.yaml`. Users with access to
-      the cert-manager-release project on GCP should be able to view logs in [GCB build history](https://console.cloud.google.com/cloud-build/builds?project=cert-manager-release).
+      > **Note 2:** For recent versions of cert-manager, the tag being pushed will trigger a Google Cloud Build job to start,
+      > kicking off a build using the steps in `gcb/build_cert_manager.yaml`. Users with access to
+      > the cert-manager-release project on GCP should be able to view logs in [GCB build history](https://console.cloud.google.com/cloud-build/builds?project=cert-manager-release).
 
-8. In this step, we make sure the Go module
+1.  In this step, we make sure the Go module
    `github.com/cert-manager/cert-manager/cmd/cmctl` can be imported by
    third-parties.
 
-    First, update the `cmd/cmctl`'s `go.mod` with the tag we just created:
+    First, create a temporary branch.
+
+     ```bash
+     # Must be run from the cert-manager repo folder.
+     git checkout -b "update-cmd/ctl/$RELEASE_VERSION"
+     ```
+
+    Second, update the `cmd/cmctl`'s `go.mod` with the tag we just created:
 
      ```bash
      # Must be run from the cert-manager repo folder.
@@ -364,7 +410,7 @@ page if a step is missing or if it is outdated.
      cd ../..
      ```
 
-    Then, create a tag for the `cmd/cmctl` module:
+    Third, create a tag for the `cmd/cmctl` module:
 
      ```bash
      # Must be run from the cert-manager repo folder.
@@ -377,53 +423,30 @@ page if a step is missing or if it is outdated.
 
     [how-are-versions-of-a-sub-module-managed]: https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
 
-9. In this section, we will be creating the description for the GitHub Release.
+    Finally, open a PR to merge that change to master with the following
+    command:
+
+    ```bash
+    gh pr create \
+      --title "[Release $RELEASE_VERSION] Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
+      --body "Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
+      --base $BRANCH --head "update-cmd/ctl/$RELEASE_VERSION"
+    ```
+    ```
+
+2.  In this section, we will be creating the description for the GitHub Release.
 
     > **Note:** This step is about creating the description that will be
     > copy-pasted into the GitHub release page. The creation of the "Release
     > Note" page on the website is done in a previous step.
 
-    1. Use the following two tables to understand how to fill in the four
-       environment variables needed for the next step. These four environment
-       variables are documented on the
-       [README](https://github.com/kubernetes/release/blob/master/cmd/release-notes/README.md#options)
-       for the Kubernetes `release-notes` tool.
-
-        | Variable          | Description                             |
-        | ----------------- | --------------------------------------- |
-        | `RELEASE_VERSION` | The git tag                             |
-        | `START_TAG`\*     | The git tag of the "previous"\* release |
-        | `END_REV`         | Name of your release branch (inclusive) |
-        | `BRANCH`          | Name of your release branch             |
-
-        Examples for each release type (e.g., initial alpha release):
-
-        | Variable          | Example 1        | Example 2        | Example 2        | Example 3     | Example 4     |
-        | ----------------- | ---------------- | ---------------- | ---------------- | ------------- | ------------- |
-        |                   |                  |                  |                  |               |               |
-        |                   | initial alpha    | subsequent alpha | beta release     | final release | patch release |
-        | `RELEASE_VERSION` | `v1.3.0-alpha.0` | `v1.3.0-alpha.1` | `v1.3.0-beta.0`  | `v1.3.0`      | `v1.3.1`      |
-        | `START_TAG`\*     | `v1.2.0`         | `v1.3.0-alpha.0` | `v1.3.0-alpha.1` | `v1.2.0`\*\*  | `v1.3.0`      |
-        | `END_REV`         | `master`         | `master`         | `release-1.3`    | `release-1.3` | `release-1.3` |
-        | `BRANCH`          | `master`         | `master`         | `release-1.3`    | `release-1.3` | `release-1.3` |
-
-        > \*The git tag of the "previous" release (`START_TAG`) depends on which
-        > type of release you count on doing. Look at the above examples to
-        > understand a bit more what those are.
-
-        > \*\*Do not use a patch here (e.g., no `v1.2.3`). It must be `v1.2.0`:
-        > you must use the latest tag that belongs to the release branch you are
-        > releasing on; in the above example, the release branch is
-        > `release-1.3`, and the latest tag on that branch is `v1.2.0`.
-
-        After finding out the value for each of the 4 environment variables, set
-        the variables in your shell (for example, following the example 1):
+    1. Check that all the env vars are ready:
 
         ```bash
-        export RELEASE_VERSION="v1.3.0-alpha.0"
-        export START_TAG="v1.2.0"
-        export END_REV="release-1.3"
-        export BRANCH="release-1.3"
+        echo $RELEASE_VERSION
+        echo $START_TAG
+        echo $END_REV
+        echo $BRANCH
         ```
 
     2. Generate `github-release-description.md` with the following command:
@@ -448,7 +471,7 @@ page if a step is missing or if it is outdated.
     4. **(final release only)** Write the section "Community" by taking example
        on past GitHub Releases.
 
-10. Check that the build is complete and send Slack messages about the release:
+3.  Check that the build is complete and send Slack messages about the release:
 
     1. For recent versions of cert-manager, the build will have been automatically
        triggered by the tag being pushed earlier. You can check if it's complete on
@@ -487,7 +510,7 @@ page if a step is missing or if it is outdated.
         Follow the <code>cmrel makestage</code> build: https://console.cloud.google.com/cloud-build/builds/7641734d-fc3c-42e7-9e4c-85bfc4d1d547?project=1021342095237
         </p></div>
 
-11. Run `cmrel publish`:
+4.  Run `cmrel publish`:
 
     1. Do a `cmrel publish` dry-run to ensure that all the staged resources are
        valid. Run the following command:
@@ -532,7 +555,7 @@ page if a step is missing or if it is outdated.
         Follow the <code>cmrel publish</code> build: https://console.cloud.google.com/cloud-build/builds/b6fef12b-2e81-4486-9f1f-d00592351789?project=1021342095237
         </p></div>
 
-12. Publish the GitHub release:
+5.  Publish the GitHub release:
 
     1. Visit the draft GitHub release and paste in the release notes that you
        generated earlier. You will need to manually edit the content to match
@@ -547,7 +570,7 @@ page if a step is missing or if it is outdated.
 
     4. Click "Publish" to make the GitHub release live.
 
-13. Merge the pull request containing the Helm chart:
+6.  Merge the pull request containing the Helm chart:
 
     The Helm charts for cert-manager are served using Cloudflare pages
     and the Helm chart files and metadata are stored in the [Jetstack charts repository](https://github.com/jetstack/jetstack-charts).
@@ -559,7 +582,7 @@ page if a step is missing or if it is outdated.
     4. Merge the PR
     5. Check that the [cert-manager Helm chart is visible on ArtifactHUB](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
 
-14. **(final + patch releases)** Merge the 4 Website PRs:
+7.  **(final + patch releases)** Merge the 4 Website PRs:
 
     1. Merge the PRs "Release Notes", "Upgrade Notes", and "Freeze And Bump
        Versions" that you have created previously.
@@ -577,7 +600,7 @@ page if a step is missing or if it is outdated.
 
       [ff-release-next]: https://github.com/cert-manager/website/compare/master...release-next?quick_pull=1&title=%5BPost-Release%5D+Merge+release-next+into+master&body=%3C%21--%0A%0AThe+command+%22%2Foverride+dco%22+is+necessary+because+some+the+merge+commits%0Ahave+been+written+by+the+bot+and+do+not+have+a+DCO+signoff.%0A%0A--%3E%0A%0A%2Foverride+dco
 
-15. Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
+8.  Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
 
     Assuming you have `brew` installed, you can use the `brew bump-formula-pr`
     command to do this. You'll need the new tag name and the commit hash of that
@@ -594,7 +617,7 @@ page if a step is missing or if it is outdated.
     against https://github.com/homebrew/homebrew-core has been opened, continue
     with further release steps.
 
-16. Post a Slack message as an answer to the first message. Toggle the check
+9.  Post a Slack message as an answer to the first message. Toggle the check
    box "Also send to `#cert-manager-dev`" so that the message is well
    visible. Also cross-post the message on `#cert-manager`.
 
@@ -602,7 +625,7 @@ page if a step is missing or if it is outdated.
     https://github.com/cert-manager/cert-manager/releases/tag/v1.0.0 🎉
     </p></div>
 
-17. **(final release only)** Show the release to the world:
+10. **(final release only)** Show the release to the world:
 
     1. Send an email to
        [`cert-manager-dev@googlegroups.com`](https://groups.google.com/g/cert-manager-dev)
@@ -615,7 +638,7 @@ page if a step is missing or if it is outdated.
     3. Send a toot from the cert-manager Mastodon account! Login details are in Jetstack's 1password (for now).
        ([Example toot](https://infosec.exchange/@CertManager/109666434738850493))
 
-18. Proceed to the post-release "testing and release" steps:
+11. Proceed to the post-release "testing and release" steps:
 
     1. **(initial beta only)** Create a PR on
        [cert-manager/release](https://github.com/cert-manager/release) in order to

From fabe0ed8be065deb2687595f9fd1fa634b145f8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 19:24:32 +0200
Subject: [PATCH 11/16] release-process: typos and fix ordered list numbering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 58 ++++++++++----------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 173b3010e6..96359c287c 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -145,7 +145,8 @@ page if a step is missing or if it is outdated.
 
    [^1]: One or more "patch pre-releases" may be created to allow voluntary community testing of a bug fix or security fix before the fix is made generally available. The suffix `-beta` must be used for patch pre-releases.
 
-2. Set the 4 env variables by copying the following snippet in your shell table:
+2. Set the 4 environment variables by copying the following snippet in your
+   shell table:
 
      ```bash
      export RELEASE_VERSION="v1.3.0-alpha.0"
@@ -388,7 +389,7 @@ page if a step is missing or if it is outdated.
       > kicking off a build using the steps in `gcb/build_cert_manager.yaml`. Users with access to
       > the cert-manager-release project on GCP should be able to view logs in [GCB build history](https://console.cloud.google.com/cloud-build/builds?project=cert-manager-release).
 
-1.  In this step, we make sure the Go module
+9. In this step, we make sure the Go module
    `github.com/cert-manager/cert-manager/cmd/cmctl` can be imported by
    third-parties.
 
@@ -423,24 +424,23 @@ page if a step is missing or if it is outdated.
 
     [how-are-versions-of-a-sub-module-managed]: https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
 
-    Finally, open a PR to merge that change to master with the following
-    command:
+    Finally, open a PR to merge that change and go back to the release branch
+    with the following commands:
 
     ```bash
     gh pr create \
       --title "[Release $RELEASE_VERSION] Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
-      --body "Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
-      --base $BRANCH --head "update-cmd/ctl/$RELEASE_VERSION"
-    ```
+      --body "Update cmd/cmctl's go.mod to $RELEASE_VERSION" --base $BRANCH
+    git checkout $BRANCH
     ```
 
-2.  In this section, we will be creating the description for the GitHub Release.
+10. In this section, we will be creating the description for the GitHub Release.
 
     > **Note:** This step is about creating the description that will be
     > copy-pasted into the GitHub release page. The creation of the "Release
     > Note" page on the website is done in a previous step.
 
-    1. Check that all the env vars are ready:
+    1. Check that all the 4 environment variables are ready:
 
         ```bash
         echo $RELEASE_VERSION
@@ -471,7 +471,7 @@ page if a step is missing or if it is outdated.
     4. **(final release only)** Write the section "Community" by taking example
        on past GitHub Releases.
 
-3.  Check that the build is complete and send Slack messages about the release:
+11. Check that the build is complete and send Slack messages about the release:
 
     1. For recent versions of cert-manager, the build will have been automatically
        triggered by the tag being pushed earlier. You can check if it's complete on
@@ -510,7 +510,7 @@ page if a step is missing or if it is outdated.
         Follow the <code>cmrel makestage</code> build: https://console.cloud.google.com/cloud-build/builds/7641734d-fc3c-42e7-9e4c-85bfc4d1d547?project=1021342095237
         </p></div>
 
-4.  Run `cmrel publish`:
+12. Run `cmrel publish`:
 
     1. Do a `cmrel publish` dry-run to ensure that all the staged resources are
        valid. Run the following command:
@@ -537,17 +537,17 @@ page if a step is missing or if it is outdated.
         cmrel publish --nomock --release-name "$RELEASE_VERSION"
         ```
 
-      <div className="info">
-         ⏰ Upon completion there will be:
-         <ol>
-            <li>
-               <a href="https://github.com/cert-manager/cert-manager/releases">A draft release of cert-manager on GitHub</a>
-            </li>
-            <li>
-               <a href="https://github.com/jetstack/jetstack-charts/pulls">A pull request containing the new Helm chart</a>
-            </li>
-         </ol>
-      </div>
+       <div className="info">
+          ⏰ Upon completion there will be:
+          <ol>
+             <li>
+                <a href="https://github.com/cert-manager/cert-manager/releases">A draft release of cert-manager on GitHub</a>
+             </li>
+             <li>
+                <a href="https://github.com/jetstack/jetstack-charts/pulls">A pull request containing the new Helm chart</a>
+             </li>
+          </ol>
+       </div>
 
     4. While the build is running, send a fourth Slack message in reply to the first message:
 
@@ -555,7 +555,7 @@ page if a step is missing or if it is outdated.
         Follow the <code>cmrel publish</code> build: https://console.cloud.google.com/cloud-build/builds/b6fef12b-2e81-4486-9f1f-d00592351789?project=1021342095237
         </p></div>
 
-5.  Publish the GitHub release:
+13. Publish the GitHub release:
 
     1. Visit the draft GitHub release and paste in the release notes that you
        generated earlier. You will need to manually edit the content to match
@@ -570,7 +570,7 @@ page if a step is missing or if it is outdated.
 
     4. Click "Publish" to make the GitHub release live.
 
-6.  Merge the pull request containing the Helm chart:
+14. Merge the pull request containing the Helm chart:
 
     The Helm charts for cert-manager are served using Cloudflare pages
     and the Helm chart files and metadata are stored in the [Jetstack charts repository](https://github.com/jetstack/jetstack-charts).
@@ -582,7 +582,7 @@ page if a step is missing or if it is outdated.
     4. Merge the PR
     5. Check that the [cert-manager Helm chart is visible on ArtifactHUB](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
 
-7.  **(final + patch releases)** Merge the 4 Website PRs:
+15. **(final + patch releases)** Merge the 4 Website PRs:
 
     1. Merge the PRs "Release Notes", "Upgrade Notes", and "Freeze And Bump
        Versions" that you have created previously.
@@ -600,7 +600,7 @@ page if a step is missing or if it is outdated.
 
       [ff-release-next]: https://github.com/cert-manager/website/compare/master...release-next?quick_pull=1&title=%5BPost-Release%5D+Merge+release-next+into+master&body=%3C%21--%0A%0AThe+command+%22%2Foverride+dco%22+is+necessary+because+some+the+merge+commits%0Ahave+been+written+by+the+bot+and+do+not+have+a+DCO+signoff.%0A%0A--%3E%0A%0A%2Foverride+dco
 
-8.  Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
+16. Open a PR for a [Homebrew](https://github.com/Homebrew/homebrew-core/pulls) formula update for `cmctl`.
 
     Assuming you have `brew` installed, you can use the `brew bump-formula-pr`
     command to do this. You'll need the new tag name and the commit hash of that
@@ -617,7 +617,7 @@ page if a step is missing or if it is outdated.
     against https://github.com/homebrew/homebrew-core has been opened, continue
     with further release steps.
 
-9.  Post a Slack message as an answer to the first message. Toggle the check
+17. Post a Slack message as an answer to the first message. Toggle the check
    box "Also send to `#cert-manager-dev`" so that the message is well
    visible. Also cross-post the message on `#cert-manager`.
 
@@ -625,7 +625,7 @@ page if a step is missing or if it is outdated.
     https://github.com/cert-manager/cert-manager/releases/tag/v1.0.0 🎉
     </p></div>
 
-10. **(final release only)** Show the release to the world:
+18. **(final release only)** Show the release to the world:
 
     1. Send an email to
        [`cert-manager-dev@googlegroups.com`](https://groups.google.com/g/cert-manager-dev)
@@ -638,7 +638,7 @@ page if a step is missing or if it is outdated.
     3. Send a toot from the cert-manager Mastodon account! Login details are in Jetstack's 1password (for now).
        ([Example toot](https://infosec.exchange/@CertManager/109666434738850493))
 
-11. Proceed to the post-release "testing and release" steps:
+19. Proceed to the post-release "testing and release" steps:
 
     1. **(initial beta only)** Create a PR on
        [cert-manager/release](https://github.com/cert-manager/release) in order to

From fe48763cf9aef4089a3147b7c7ade90da2276219 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 19:33:48 +0200
Subject: [PATCH 12/16] release-process: add a release-note block to the "gh pr
 create"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 28 +++++++++++++++-----
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 96359c287c..06ddc0c7db 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -406,6 +406,7 @@ page if a step is missing or if it is outdated.
      # Must be run from the cert-manager repo folder.
      cd cmd/cmctl
      go get github.com/cert-manager/cert-manager@$RELEASE_VERSION
+     go mod tidy
      git add go.mod go.sum
      git commit -m"Update cmd/cmctl's go.mod to $RELEASE_VERSION"
      cd ../..
@@ -424,15 +425,28 @@ page if a step is missing or if it is outdated.
 
     [how-are-versions-of-a-sub-module-managed]: https://stackoverflow.com/questions/60601011/how-are-versions-of-a-sub-module-managed/60601402#60601402
 
-    Finally, open a PR to merge that change and go back to the release branch
+    Then, open a PR to merge that change and go back to the release branch
     with the following commands:
 
-    ```bash
-    gh pr create \
-      --title "[Release $RELEASE_VERSION] Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
-      --body "Update cmd/cmctl's go.mod to $RELEASE_VERSION" --base $BRANCH
-    git checkout $BRANCH
-    ```
+     ```bash
+     gh pr create \
+       --title "[Release $RELEASE_VERSION] Update cmd/cmctl's go.mod to $RELEASE_VERSION" \
+       --body-file - --base $BRANCH <<EOF
+     This PR cmd/cmctl's go.mod to $RELEASE_VERSION as part of the release process.
+
+     **To the reviewer:** the version changes in \`go.mod\` must be reviewed.
+
+     \`\`\`release-note
+     NONE
+     \`\`\`
+     EOF
+     ```
+
+    Finally, get back to the main tag:
+
+     ```bash
+     git checkout $RELEASE_VERSION
+     ```
 
 10. In this section, we will be creating the description for the GitHub Release.
 

From c32e19a757ee39b9ac061289417b2bdb591c9543 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Tue, 20 Jun 2023 20:08:41 +0200
Subject: [PATCH 13/16] release-process: tell ppl that we need to run "go mod
 tidy" everywhere
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 06ddc0c7db..58a3db63cd 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -406,10 +406,11 @@ page if a step is missing or if it is outdated.
      # Must be run from the cert-manager repo folder.
      cd cmd/cmctl
      go get github.com/cert-manager/cert-manager@$RELEASE_VERSION
-     go mod tidy
-     git add go.mod go.sum
-     git commit -m"Update cmd/cmctl's go.mod to $RELEASE_VERSION"
      cd ../..
+
+     find . -name go.mod -not -path ./_bin/\* -exec dirname '{}' \; | xargs -L1 -I@ sh -c 'cd @; go mod tidy'
+     git add **/go.mod **/go.sum
+     git commit -m"Update cmd/cmctl's go.mod to $RELEASE_VERSION"
      ```
 
     Third, create a tag for the `cmd/cmctl` module:

From b4a18ec0e615e3d373ea05ead9e9b58221d5eb08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Fri, 23 Jun 2023 18:42:58 +0200
Subject: [PATCH 14/16] release-process: don't show a menu item for "Release
 Notes"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

My previous script didn't remove the "routes" fields that had
an empty array, which meant it was showing in the menu for
no reason.

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 58a3db63cd..de57065254 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -283,8 +283,10 @@ page if a step is missing or if it is outdated.
       cp -r content/docs content/v1.12-docs
       rm -rf content/v1.12-docs/{installation/supported-releases,installation/upgrading,release-notes}
       sed -i.bak 's|docs|v1.12-docs|g' content/v1.12-docs/manifest.json
-      jq 'del(.. | select(.path? | select(.) | test(".*(installation/supported-releases.md|installation/upgrading|release-notes).*")))' \
-         content/v1.12-docs/manifest.json >tmp && mv tmp content/v1.12-docs/manifest.json
+      cat content/v1.12-docs/manifest.json \
+        | jq 'del(.. | select(.path? | select(.) | test(".*(installation/supported-releases.md|installation/upgrading|release-notes).*")))' \
+        | jq 'del(.. | select(.routes? == []))' >/tmp/manifest \
+           && mv /tmp/manifest content/v1.12-docs/manifest.json
       ```
 
    6. (**final + patch releases**) Update the [API docs](https://cert-manager.io/docs/reference/api-docs/) and [CLI docs](https://cert-manager.io/docs/cli//):

From 26068830a2081903faca6f0c0a29e0f61864eff7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Fri, 23 Jun 2023 19:16:31 +0200
Subject: [PATCH 15/16] release-process: code review suggestions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Ashley Davis <SgtCoDFish@users.noreply.github.com>
Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index de57065254..22cd6c6a1b 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -269,7 +269,7 @@ page if a step is missing or if it is outdated.
       rm -f **/*.bak
       ```
 
-      To check that all mentions of that versions are gone, run:
+      To check that all mentions of that version are gone, run:
 
       ```bash
       grep -R -n -F 'v1.11.' content/docs/installation
@@ -485,8 +485,7 @@ page if a step is missing or if it is outdated.
         </p></div>
     3. Add a one-sentence summary at the top.
 
-    4. **(final release only)** Write the section "Community" by taking example
-       on past GitHub Releases.
+    4. **(final release only)** Write the "Community" section, following the example of past releases such as [v1.12.0](https://github.com/cert-manager/cert-manager/releases/tag/v1.12.0). If there are any users who didn't make code contributions but helped in other ways (testing, PR discussion, etc), be sure to thank them here!
 
 11. Check that the build is complete and send Slack messages about the release:
 

From 26ea4ef4ad5e83fc34e7824da4ab8b3c84992248 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ma=C3=ABl=20Valais?= <mael@vls.dev>
Date: Sat, 24 Jun 2023 22:27:38 +0200
Subject: [PATCH 16/16] release-process: fix duplicate heading
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maël Valais <mael@vls.dev>
---
 content/docs/contributing/release-process.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/docs/contributing/release-process.md b/content/docs/contributing/release-process.md
index 22cd6c6a1b..6b508477b8 100644
--- a/content/docs/contributing/release-process.md
+++ b/content/docs/contributing/release-process.md
@@ -239,9 +239,9 @@ page if a step is missing or if it is outdated.
 
    8. Add a line to the file `content/docs/release-notes/README.md`.
 
-5. **(final + patch release)** Prepare the Website "Release Notes" PR.
+5. **(final + patch release)** Prepare the Website "Bump Versions" PR.
 
-   > ⚠️ This step can be done ahead of time.
+   **⚠️ This step can be done ahead of time.**
 
    In that PR: