doc: update release/README.md (#6920)

release/README.md

@@ -1,24 +1,24 @@
 # Creating a new release of google-cloud-cpp
 
-Unless there are no changes, we create releases for `google-cloud-cpp` every
-4 weeks, or if there is a major announcement or change to the status of one
+Unless there are no changes, we create releases for `google-cloud-cpp` at the
+beginning of each month, usually on the first business day. We also create
+releases if there is a major announcement or change to the status of one
 of the libraries (like reaching the "Alpha" or "Beta" milestone).
 
 The intended audience of this document are developers in the `google-cloud-cpp`
-project that need to create a new release. The audience is expected to be
-familiar with the project itself, [git][git-docs], [GitHub][github-guides],
+project that need to create a new release. We expect the reader to be familiar
+the project itself, [git][git-docs], [GitHub][github-guides], and
 [semantic versioning](https://semver.org).
 
 ## Preparing for a release
 
-Assuming you are working on your own fork of the `google-cloud-cpp` project,
-and `upstream` points to the `googleapis/google-cloud-cpp` remote, these
-commands should be useful in identifying important changes for inclusion in the
-release notes.
+To create a new release you need to perform some maintenance tasks, these are
+enumerated below.
 
 ### Verify CI passing
+
 Before beginning the release process, verify all CI builds are passing on
-main.
+the `main` branch. This is displayed in the GitHub page for the project.
 
 ### Update the API baseline
 
@@ -38,6 +38,11 @@ can, but are not required to, send a single PR to update the baseline and the
 
 ### Update CHANGELOG.md
 
+Assuming you are working on your own fork of the `google-cloud-cpp` project,
+and `upstream` points to the `googleapis/google-cloud-cpp` remote, these
+commands should be useful in identifying important changes for inclusion in the
+release notes.
+
 Update `CHANGELOG.md` based on the release notes for Bigtable, Storage,
 Spanner, and the common libraries:
 
@@ -86,17 +91,24 @@ discarded as they are uninteresting to our users.
 
 ### Send a PR with all these changes
 
-It is not recommended that you create the release branch before this PR is
-*merged*, but in some circumstances it might be needed, for example, if a large
-change that could destabilize the release is about to be merged, or if we want
-to create the release at an specific point in the revision history.
+In general, do not create the release branch before this PR is *merged*. We want
+to create the release from a stable point in the default branch (`main`), and
+we want this point to include the updated release notes and API baselines.
+There may be exceptions to this guideline, you are encouraged to use your own
+judgment.
 
 ## Creating the release
 
+> :warning: the `release.sh` script was broken as of 2021-07.
+> See [#6682] for details
+
+[#6682]: https://github.com/googleapis/google-cloud-cpp/issues/6682
+
 We next need to create the release tag, the release branch, and create the
-release in the GitHub UI. These steps are handled automatically for us by the
-[`release/release.sh`
-script](https://github.com/googleapis/google-cloud-cpp/blob/main/release/release.sh).
+release in the GitHub UI. We use a script ([`release/release.sh`]) to automate
+said steps.
+
+[`release/release.sh`]: https://github.com/googleapis/google-cloud-cpp/blob/main/release/release.sh
 
 *No PR is needed for this step.*
 
@@ -125,9 +137,9 @@ everything looks OK, uncheck the pre-release checkbox and publish.
 
 ## Check the published docs on googleapis.dev
 
-After the release branch is submitted, the `publish-docs` build will be
-automatically triggered, and it will upload the docs for the new release to the
-following URLs:
+The `publish-docs` build should start automatically when you create the release
+branch. This build will upload the docs for the new release to the following
+URLs:
 
 * https://googleapis.dev/cpp/google-cloud-bigtable/latest/
 * https://googleapis.dev/cpp/google-cloud-pubsub/latest/
@@ -142,8 +154,8 @@ https://console.cloud.google.com/cloud-build/builds?project=cloud-cpp-testing-re
 ## Bump the version numbers in `main`
 
 Working in your fork of `google-cloud-cpp`: bump the version numbers to the
-*next* version (i.e., one version past the release you just did above), and
-send the PR for review against `main` You need to:
+*next* version, i.e., one version past the release you just did above. Then
+send the PR for review against `main`. You need to:
 
 - Update the version numbers in the top-level `CMakeLists.txt` file.
 - Run the cmake configuration step, this will update the different
@@ -166,8 +178,10 @@ Please note that we use more strict settings for release branches than for
   * The `Require branches to be up to date before merging` sub-option
     is set. This prevents two merges that do not conflict, but nevertheless
     break if both are pushed, to actually merge.
-  * _At a minimum_ the `cla/google`, `asan-pr`, and `clang-tidy-pr` checks are
-    required to pass, but more may be selected.
+  * _At a minimum_ the `cla/google`, `asan-pr`, and `clang-tidy-pr` checks should
+    be marked as "required". You may consider adding additional builds if it
+    would prevent embarrassing failures, but consider the tradeoff of merges
+    blocked by flaky builds.
 
 * The `Include administrators` checkbox is turned on, we want to stop ourselves
   from making mistakes.
@@ -181,10 +195,10 @@ Please note that we use more strict settings for release branches than for
 
 ## Push the release to Microsoft vcpkg
 
-Nudge coryan@ to send a PR to
-[vcpkg](https://github.com/Microsoft/vcpkg/tree/master/ports/google-cloud-cpp).
-The PRs are not difficult, but contributing to this repository requires SVP
-approval.
+Nudge `coryan@` to update our [vcpkg port]. These updates are not difficult, but
+contributing to this repository requires SVP approval. If you want, you can
+seek approval to make such updates yourself, just keep in mind that this may
+take several weeks.
 
 # Creating a patch release of google-cloud-cpp on an existing release branch
 
@@ -194,9 +208,10 @@ In your development fork:
 * Create or cherry-pick commits with the desired changes.
 * Update `CHANELOG.md` to reflect the changes made.
 * Bump the minor version number in the top-level CMakeLists.txt and run the
-cmake configuration step to update the different `version_info.h` files.
-* After merging the PR(s) with all the above changes, use the Release gui on
-github to create a pre-release along with a new tag for the release.
+  cmake configuration step to update the different `version_info.h` files.
+* After merging the PR(s) with all the above changes, use the Release UI on
+  GitHub to create a pre-release along with a new tag for the release.
 * After review, publish the release.
-* Nudge coryan@ to send a PR to
-[vcpkg](https://github.com/Microsoft/vcpkg/tree/master/ports/google-cloud-cpp).
+* Nudge `coryan@` to update our [vcpkg port].
+
+[vcpkg port]: https://github.com/Microsoft/vcpkg/tree/master/ports/google-cloud-cpp