Merge pull request #1898 from yiannistri/update-release-steps

docs: Adjust release steps

Author: salasberryfin

docs/release-v2.md

@@ -10,9 +10,9 @@ This document describes the new release process for Turtles.
 
 We maintain 3 release branches for Turtles, one for each of the minor versions of Rancher that is under active maintenance, at any given point. This allows us to create new Turtles releases for each of the release branches as required for bug fixes and security patches. The process of cutting a new release is essentially the following:
 - [Create a new tag for the release](#create-a-new-tag-for-the-release)
+- [Write release description for non-developers](#write-release-description-for-non-developers)
 - [Update `rancher/charts` repository](#update-ranchercharts-repository)
 - [Update `rancher/rancher` repository](#update-rancherrancher-repository)
-- [Write release description for non-developers](#write-release-description-for-non-developers)
 - [Rancher Turtles Community Documentation](#rancher-turtles-community-documentation) (required only when cutting minor/major versions)
 - [Create a JIRA ticket for syncing Turtles Community Docs with Product Docs](#create-a-jira-ticket-for-syncing-turtles-community-docs-with-product-docs) (required only when cutting minor/major versions)
 
@@ -65,6 +65,12 @@ git clone [email protected]:rancher/turtles.git
   git push upstream examples/${RELEASE_TAG}
   ```
 
+### Write release description for non-developers
+
+Turtles release notes are automatically generated based on the commits that are published with the new version. However, these release notes may also include changes from older versions of Turtles, making it difficult for users to understand what has changed between the new version and the previous minor version. If that is the case, the generated release notes need to be deleted and new release notes need to be regenerated by selecting the previous minor version. For example, if the new release is `v0.25.0` then select `v0.24.0` as the previous tag rather than `Auto`, in the GitHub UI when editing the new release. While editing the release notes, the new release should also be marked as latest, if it is not an `rc` release.
+
+These commit messages are usually hard to understand for those that are not very familiar with the project and we must add a "human-readable" description of what the release brings at the beginning of release notes. [This](https://github.com/rancher/turtles/releases/tag/v0.13.0) can be used for reference. If the new release includes breaking changes or requires any sort of manual steps from the user, make sure these are clearly stated at the top of the release notes.
+
 ### Update `rancher/charts` repository
 
 **Warning**: Before updating `rancher/charts` repository, ensure that the previous [step](#create-a-new-tag-for-the-release) has created a new GitHub release for the tag. This release must include the Helm chart archive file in its assets (typically named `rancher-turtles-${RELEASE_TAG}.tgz`).
@@ -101,25 +107,10 @@ This part of the release is also automated via a GitHub Actions workflow, that n
 
 Once this workflow has finished, a new PR should have been created in the `rancher/rancher` repository that updates the selected branch with the new Turtles version. You need to review and merge this PR. When this PR gets merged, you will have completed the process of releasing a new version of Turtles and including it in an upcoming version of Rancher.
 
-### Write release description for non-developers
-
-Turtles release notes are automatically generated based on the commits that are published with the new version.
-
-These commit messages are usually hard to understand for those that are not very familiar with the project and we must add a "human-readable" description of what the release brings at the beginning of release notes. [This](https://github.com/rancher/turtles/releases/tag/v0.13.0) can be used for reference.
-
 ### Rancher Turtles Community Documentation
 
 **Note**: This step is required only when cutting minor/major versions.
 
-#### Update component versions in documentation
-
-Before publishing a new version of the documentation, component versions used in the documentation must be updated.
-
-1. Navigate to the Rancher Turtles Docs repository: [rancher/turtles-docs](https://github.com/rancher/turtles-docs)
-2. Go to `Actions` and start a new run of `Update Component Versions`.
-3. Look up the correct component versions from the [rancher/turtles](https://github.com/rancher/turtles) repository and fill them into the input fields. If any input fields are left blank, the workflow will retain the currently documented versions for those components.
-4. This will generate a new PR in the same repository that updates the documentation with the specified versions.
-
 #### Generate changelog from Turtles release notes
 
 Before publishing a new version of the documentation, a new [Changelog](https://turtles.docs.rancher.com/turtles/next/en/changelogs/index.html) must be generated to include the new release.