From eb845e6bad65cb216eb3ab079d2d65133b99ce40 Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 19:14:12 -0400 Subject: [PATCH 1/7] fix release note generation documentation Signed-off-by: Florent Poinsard --- doc/internal/release/release-cutover.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/doc/internal/release/release-cutover.md b/doc/internal/release/release-cutover.md index 5836a7353ca..d39afede5e2 100644 --- a/doc/internal/release/release-cutover.md +++ b/doc/internal/release/release-cutover.md @@ -172,15 +172,10 @@ We need to verify that _arewefastyet_ has finished the benchmark too. The script will prompt you `Pausing so release notes can be added. Press enter to continue`. We are now going to generate the release notes, continue to the next sub-step. - 2. Run the following command to generate the release notes: - 1. Release Candidate: - ```shell - go run ./go/tools/release-notes --from "v14.0.3" --to "HEAD" --version "v15.0.0-rc1" --summary "./changelog/15.0/15.0.0/summary.md" [--threads=[0-9.]] - ``` - 2. General Availability: - ```shell - go run ./go/tools/release-notes --from "v14.0.3" --to "HEAD" --version "v15.0.0" --summary "./changelog/15.0/15.0.0/summary.md" [--threads=[0-9.]] - ``` + 2. Run the following command to generate the release notes, please note that you can omit the `--summary` flag if there are no summary. + ```shell + go run ./go/tools/release-notes --version "v15.0.0" --summary "./changelog/15.0/15.0.0/summary.md" + ``` > Important note: The release note generation fetches a lot of data from the GitHub API. You might reach the API request limit. In which case you should use the `--threads=` flag and set an integer value lower than 10 (the default). From ca60fceaa512c43a83a04c4977469610b907ab71 Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 19:26:32 -0400 Subject: [PATCH 2/7] fix small issues in the release instruction and rename file + path in README Signed-off-by: Florent Poinsard --- doc/internal/README.md | 4 ++-- doc/internal/release/README.md | 2 +- .../{release-cutover.md => how-to-release.md} | 23 ++++++++----------- 3 files changed, 13 insertions(+), 16 deletions(-) rename doc/internal/release/{release-cutover.md => how-to-release.md} (92%) diff --git a/doc/internal/README.md b/doc/internal/README.md index 4cb81d7cda2..7ed4950e877 100644 --- a/doc/internal/README.md +++ b/doc/internal/README.md @@ -1,7 +1,7 @@ # Internal Documentation -The documents in this category document internal processes which are taken care of by the Vitess Team e.g. re-publishing the website [vitess.io](https://vitess.io) or creating a new release. +The documents in this category document internal processes which are taken care of by the Vitess Team e.g. creating a new release. We have put them here to increase transparency and make it easy for others to follow and improve processes. -- [**Release Instructions**](./release/README.md) \ No newline at end of file +- [**Release**](./release/README.md) \ No newline at end of file diff --git a/doc/internal/release/README.md b/doc/internal/release/README.md index 18e668fd20c..8f593ee9e66 100644 --- a/doc/internal/release/README.md +++ b/doc/internal/release/README.md @@ -4,10 +4,10 @@ This page describes the steps for cutting a new [open source release](https://gi ### Summary +- [How to Release](./how-to-release.md) - [Versioning](./versioning.md) - [Release Branches](./release-branches.md) - [Release Tags](./release-tags.md) - [Docker Images](./docker-images.md) - [Java Packages](./java-packages.md) -- [Release Cutover](./release-cutover.md) - [End Of Life Process](./eol-process.md) diff --git a/doc/internal/release/release-cutover.md b/doc/internal/release/how-to-release.md similarity index 92% rename from doc/internal/release/release-cutover.md rename to doc/internal/release/how-to-release.md index d39afede5e2..026b5b8c5f7 100644 --- a/doc/internal/release/release-cutover.md +++ b/doc/internal/release/how-to-release.md @@ -3,7 +3,7 @@ In this section we describe our current release process. Below is a summary of this document. - [**Pre-requisite for the release team**](#pre-requisites) -- [**0verview**](#overview) +- [**Overview**](#overview) - [**Pre-Release**](#pre-release) - [**Release**](#release) - [**Post-Release**](#post-release) @@ -58,6 +58,7 @@ That includes: - **Making sure the people doing the release have access to all the tools and infrastructure needed to do the release.** > - This includes write access to the Vitess repository and to the Maven repository. - **Preparing and cleaning the release notes summary.** + > - If the release does not contain significant change (i.e. a small patch release) then this step can be skipped > - One or more Pull Requests have to be submitted in advance to create and update the release summary. > - The summary files are located in: `./changelog/*.0/*.*.*/summary.md`. > - The summary file for a release candidate is the same as the one for the GA release. @@ -77,19 +78,15 @@ That includes: > - While the Vitess Operator is located in a different repository, we also need to do a release for it. > - The Operator follows the same cycle: RC1 -> GA -> Patches. > - Documentation for the pre-release of the Vitess Operator is available [here](https://github.com/planetscale/vitess-operator/blob/main/docs/release-process.md#prepare-for-release). -- **Update the release notes on `main`.** - > - One Pull Request against `main` must be created, it will contain the new release notes that we are adding in the Release Pull Request. - > - We open this Pull Request now to avoid waiting on the CI during release day. - > - All future changes to the release notes during the code freeze will need to be ported to both PRs: the one on `main` and the Release Pull Request. - **Update the website documentation.** > - We want to open a preparatory **draft** Pull Request to update the documentation. > - There are several pages we want to update: - > - [The releases page](https://vitess.io/docs/releases/), we must add the new release to the list with all its information and link. The links can be broken (404 error) while we are preparing for the release, this is fine. - > - [The local install page](https://vitess.io/docs/get-started/local/), we must use the proper version increment for this guide and the proper SHA. The SHA will have to be modified once the Release Pull Request and the release is tagged is merged. + > - [The releases page](https://vitess.io/docs/releases/), we must add the new release to the list with all its information and link. The links can be broken (404 error) while we are preparing for the release, this is fine. + > - [The local install page](https://vitess.io/docs/get-started/local/), we must use the proper version increment for this guide and the proper SHA. The SHA will have to be modified once the Release Pull Request and the release is tagged is merged. > - If we are doing a GA or RC release follow the instructions below: - > - There are two scripts in the website repository in `./tools/{ga|rc}_release.sh`, use them to update the website documentation. The scripts automate: - > - For an RC, we need to create a new version in the sidebar and mark the current version as RC. - > - For a GA, we need to mark the version we are releasing as "Stable" and the next one as "Development". + > - There are two scripts in the website repository in `./tools/{ga|rc}_release.sh`, use them to update the website documentation. The scripts automate: + > - For an RC, we need to create a new version in the sidebar and mark the current version as RC. + > - For a GA, we need to mark the version we are releasing as "Stable" and the next one as "Development". ----- @@ -102,7 +99,7 @@ On the release day, there are several things to do: - **Tag the Vitess release.** > - A guide on how to tag a version is available in the [How To Release Vitess](#how-to-release-vitess) section. - **Update the release notes on `main`.** - > - During the code freeze, we created a Pull Request against `main` to update the release notes. It must be merged. + > - One Pull Request against `main` must be created, it will contain the new release notes that we are adding in the Release Pull Request. - **Create the corresponding Vitess operator release.** > - Applies only to versions greater or equal to `v14.0.0`. > - If we are doing an RC release, then we will need to create the Vitess Operator RC too. If we are doing a GA release, we're also doing a GA release in the Operator. @@ -125,10 +122,10 @@ On the release day, there are several things to do: > - The benchmarks need to complete before announcing the blog posts or before they get cross-posted. - **Go back to dev mode on the release branch.** > - The version constants across the codebase must be updated to `SNAPSHOT`. -- **Build k8s Docker images and publish them** +- **Build k8s Docker images and publish them.** > - The docker image for `base`, `lite`, etc are built automatically by DockerHub. The k8s images however are dependent on these images and are required to be built manually. > - These images should be built after the `base` image has been built and available on DockerHub. - > - To build and publish these images, run `./release.sh` from the directory `vitess/docker`. + > - To build and publish these images, checkout to the new `git tag` and run `./release.sh` from the directory `vitess/docker`. ----- From a0fe46abdf4afcb690bec53ee149b7cd05b4a84b Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 20:00:56 -0400 Subject: [PATCH 3/7] Add a note inviting the release team to also run the releases.go script post-release note generation Signed-off-by: Florent Poinsard --- doc/internal/release/how-to-release.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/internal/release/how-to-release.md b/doc/internal/release/how-to-release.md index 026b5b8c5f7..06bb3ac3e32 100644 --- a/doc/internal/release/how-to-release.md +++ b/doc/internal/release/how-to-release.md @@ -174,6 +174,8 @@ We need to verify that _arewefastyet_ has finished the benchmark too. go run ./go/tools/release-notes --version "v15.0.0" --summary "./changelog/15.0/15.0.0/summary.md" ``` + > Make sure to also run `go run ./go/tools/releases/releases.go` to update the `./changelog` directory. + > Important note: The release note generation fetches a lot of data from the GitHub API. You might reach the API request limit. In which case you should use the `--threads=` flag and set an integer value lower than 10 (the default). From 33cb0f0569a4b5c28c8a61cae4c7533924739b4f Mon Sep 17 00:00:00 2001 From: Florent Poinsard <35779988+frouioui@users.noreply.github.com> Date: Fri, 15 Sep 2023 20:16:12 -0400 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Deepthi Sigireddi Signed-off-by: Florent Poinsard <35779988+frouioui@users.noreply.github.com> --- doc/internal/release/how-to-release.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/internal/release/how-to-release.md b/doc/internal/release/how-to-release.md index 06bb3ac3e32..adfee159f7e 100644 --- a/doc/internal/release/how-to-release.md +++ b/doc/internal/release/how-to-release.md @@ -58,7 +58,7 @@ That includes: - **Making sure the people doing the release have access to all the tools and infrastructure needed to do the release.** > - This includes write access to the Vitess repository and to the Maven repository. - **Preparing and cleaning the release notes summary.** - > - If the release does not contain significant change (i.e. a small patch release) then this step can be skipped + > - If the release does not contain significant changes (i.e. a small patch release) then this step can be skipped > - One or more Pull Requests have to be submitted in advance to create and update the release summary. > - The summary files are located in: `./changelog/*.0/*.*.*/summary.md`. > - The summary file for a release candidate is the same as the one for the GA release. @@ -81,8 +81,8 @@ That includes: - **Update the website documentation.** > - We want to open a preparatory **draft** Pull Request to update the documentation. > - There are several pages we want to update: - > - [The releases page](https://vitess.io/docs/releases/), we must add the new release to the list with all its information and link. The links can be broken (404 error) while we are preparing for the release, this is fine. - > - [The local install page](https://vitess.io/docs/get-started/local/), we must use the proper version increment for this guide and the proper SHA. The SHA will have to be modified once the Release Pull Request and the release is tagged is merged. + > - [The releases page](https://vitess.io/docs/releases/): we must add the new release to the list with all its information and link. The links can be broken (404 error) while we are preparing for the release, this is fine. + > - [The local install page](https://vitess.io/docs/get-started/local/): we must use the proper version increment for this guide and the proper SHA. The SHA will have to be modified once the Release Pull Request and the release is tagged is merged. > - If we are doing a GA or RC release follow the instructions below: > - There are two scripts in the website repository in `./tools/{ga|rc}_release.sh`, use them to update the website documentation. The scripts automate: > - For an RC, we need to create a new version in the sidebar and mark the current version as RC. @@ -169,7 +169,7 @@ We need to verify that _arewefastyet_ has finished the benchmark too. The script will prompt you `Pausing so release notes can be added. Press enter to continue`. We are now going to generate the release notes, continue to the next sub-step. - 2. Run the following command to generate the release notes, please note that you can omit the `--summary` flag if there are no summary. + 2. Run the following command to generate the release notes. Note that you can omit the `--summary` flag if there are no summary. ```shell go run ./go/tools/release-notes --version "v15.0.0" --summary "./changelog/15.0/15.0.0/summary.md" ``` From 4d509fc185792ea4724f2a497375425ce89cecdb Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 20:19:14 -0400 Subject: [PATCH 5/7] fix review suggestion Signed-off-by: Florent Poinsard --- doc/internal/release/how-to-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internal/release/how-to-release.md b/doc/internal/release/how-to-release.md index adfee159f7e..8b72002d887 100644 --- a/doc/internal/release/how-to-release.md +++ b/doc/internal/release/how-to-release.md @@ -125,7 +125,7 @@ On the release day, there are several things to do: - **Build k8s Docker images and publish them.** > - The docker image for `base`, `lite`, etc are built automatically by DockerHub. The k8s images however are dependent on these images and are required to be built manually. > - These images should be built after the `base` image has been built and available on DockerHub. - > - To build and publish these images, checkout to the new `git tag` and run `./release.sh` from the directory `vitess/docker`. + > - To build and publish these images, checkout the new release tag that was just created and run `./release.sh` from the directory `./docker. ----- From 136c7805687d7e6e13df69858578cc9081bce2ff Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 20:20:23 -0400 Subject: [PATCH 6/7] fix review suggestion Signed-off-by: Florent Poinsard --- doc/internal/release/how-to-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internal/release/how-to-release.md b/doc/internal/release/how-to-release.md index 8b72002d887..21c43d8c76a 100644 --- a/doc/internal/release/how-to-release.md +++ b/doc/internal/release/how-to-release.md @@ -85,7 +85,7 @@ That includes: > - [The local install page](https://vitess.io/docs/get-started/local/): we must use the proper version increment for this guide and the proper SHA. The SHA will have to be modified once the Release Pull Request and the release is tagged is merged. > - If we are doing a GA or RC release follow the instructions below: > - There are two scripts in the website repository in `./tools/{ga|rc}_release.sh`, use them to update the website documentation. The scripts automate: - > - For an RC, we need to create a new version in the sidebar and mark the current version as RC. + > - For an RC, we need to create a new entry in the sidebar which represents the next version on `main` and mark the version we are releasing as RC. > - For a GA, we need to mark the version we are releasing as "Stable" and the next one as "Development". ----- From 803b6061801865014d5796365dd0ccfb57c362e2 Mon Sep 17 00:00:00 2001 From: Florent Poinsard Date: Fri, 15 Sep 2023 20:22:22 -0400 Subject: [PATCH 7/7] self-review Signed-off-by: Florent Poinsard --- doc/internal/release/how-to-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/internal/release/how-to-release.md b/doc/internal/release/how-to-release.md index 21c43d8c76a..450127bd869 100644 --- a/doc/internal/release/how-to-release.md +++ b/doc/internal/release/how-to-release.md @@ -125,7 +125,7 @@ On the release day, there are several things to do: - **Build k8s Docker images and publish them.** > - The docker image for `base`, `lite`, etc are built automatically by DockerHub. The k8s images however are dependent on these images and are required to be built manually. > - These images should be built after the `base` image has been built and available on DockerHub. - > - To build and publish these images, checkout the new release tag that was just created and run `./release.sh` from the directory `./docker. + > - To build and publish these images, checkout the new release tag that was just created and run `./release.sh` from the directory `./docker`. -----