From 98ff1e8f3dc41be18cb90b0668e6b5c260383a38 Mon Sep 17 00:00:00 2001 From: Robert van Gent Date: Wed, 19 Jul 2023 17:20:40 -0700 Subject: [PATCH] docs: update release instructions (#3280) --- internal/docs/release.md | 65 +++------- internal/testing/check_api_change.sh | 102 ---------------- internal/testing/prerelease.sh | 175 --------------------------- internal/testing/runchecks.sh | 9 -- 4 files changed, 20 insertions(+), 331 deletions(-) delete mode 100755 internal/testing/check_api_change.sh delete mode 100755 internal/testing/prerelease.sh diff --git a/internal/docs/release.md b/internal/docs/release.md index c70e95a01d..2ba9764eab 100644 --- a/internal/docs/release.md +++ b/internal/docs/release.md @@ -2,29 +2,16 @@ To do a release: -- Announce to the team that a release is in progress - avoid merging PRs - during the release window (likely 1-2 hours). TODO(eliben): find a way to - enforce this on GitHub. - -- Make sure all tests pass locally with `runchecks.sh` and the build is - green. - -- Run the prerelease checks until everything is passing. - - - Create a new branch (`git checkout -B prerelease`). Running the script - will modify hundreds of golden files, so you want to do it in a branch. - You can delete the branch and abandon all the changes when you are done. - - Run `./internal/testing/prerelease.sh init` until it finishes with - `SUCCESS`. Note that there are some known failures that are logged but - don't prevent overall `SUCCESS`. - - Run `./internal/testing/prerelease.sh run`. Again, there are some known - failures. You can re-run any unexpected failures independently to - investigate; see the `prerelease.sh` script to see the exact command - line to use. - - Run `./internal/testing/prerelease.sh cleanup` when you are done. - - Delete the branch (`-D` to force deleting with uncommitted changes). - -- Create a new branch for the release (`git checkout -B release`). +- Pick the new release name; it's probably `v0.x.0` where `x` is whatever the + [last release](https://github.com/google/go-cloud/releases/latest) was plus + one, but follow [semantic versioning](https://semver.org/). + +- Consider updating dependencies via `internal/testing/update_deps.sh` if it + hasn't been done recently. Do this as a separte step before the release. + +- Create a new branch for the release (`git checkout -B prerelease`). + +- Update the `User-Agent` version in internal/useragent/useragent.go. - Run the release helper tool to remove `replace` lines from the `go.mod` files of submodules: @@ -33,12 +20,6 @@ To do a release: $ go run internal/releasehelper/releasehelper.go dropreplace ``` - Check that everything looks in order (with `git diff`) and commit. - -- Pick the new release name; it's probably `v0.x.0` where `x` is whatever the - [last release](https://github.com/google/go-cloud/releases/latest) was plus - one, but follow [semantic versioning](https://semver.org/). - - Run the release helper tool to set the version in `require` directives of submodules to the new (yet unreleased) version: @@ -46,19 +27,20 @@ To do a release: $ go run internal/releasehelper/releasehelper.go setversion v0.x.0 ``` - Check that everything looks in order (with `git diff`) and commit. +- Commit and create a PR. Tests will fail for this PR because submodules depend on a + version of the main module that wasn't tagged yet, so you may have to + force-merge the PR. Note that this does not affect users, since a new + version hasn't been tagged yet. -- Create a PR. Tests will fail for this PR because submodules depend on a - version of the main module that wasn't tagged yet. Enable force merging in - GitHub settings and force-merge the PR. Note that this does not affect - users, since a new version hasn't been tagged yet. +- `git sync` your local client and move to the master branch. -- Tag new versions for all modules marked to be released (`yes` in the `released` column) - in the `./allmodules` file with `./internal/testing/git_tag_modules.sh v0.X.0`. +- Tag new versions by running `./internal/testing/git_tag_modules.sh v0.X.0`. - Push tags to upstream with `git push upstream --tags` -- Compile release notes by reviewing the commits since the last release (use +- Go to [Releases](https://github.com/google/go-cloud/releases). Click `Draft + a new release`, enter your release name, select your tag from the dropdown, + and enter release notes by reviewing the commits since the last release (use the [Compare](https://github.com/google/go-cloud/compare/v0.1.1...v0.2.0) page for this). @@ -68,15 +50,11 @@ To do a release: - List highlights in the form: `****: `. For example, `**blob**: Added feature foo.`. -- Go to [Releases](https://github.com/google/go-cloud/releases). Click `Draft - a new release`, enter your release name, select your tag from the dropdown, - and enter your release notes. - - Send an email to [go-cloud@googlegroups.com](https://groups.google.com/forum/#!forum/go-cloud) announcing the release, and including the release notes. -- Disable force pushing on GitHub. +- Create a new branch for the postrelease (`git checkout -B postrelease`). - Add back `replace` lines: @@ -85,6 +63,3 @@ To do a release: ``` Run tests and send out a PR as usual. - -- Update dependencies by running `internal/testing/update_deps.sh`, run tests - and send out a PR. diff --git a/internal/testing/check_api_change.sh b/internal/testing/check_api_change.sh deleted file mode 100755 index e5c32192c1..0000000000 --- a/internal/testing/check_api_change.sh +++ /dev/null @@ -1,102 +0,0 @@ -#!/usr/bin/env bash -# Copyright 2019 The Go Cloud Development Kit Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# https://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# This script checks to see if there are any incompatible API changes on the -# current branch relative to the upstream branch. -# It fails if it finds any, unless there is a commit with BREAKING_CHANGE_OK -# in the first line of the commit message. -# -# It checks all modules listed in allmodules, and skips packages with -# "internal" or "test" in their name. -# -# It expects to be run at the root of the repository, and that HEAD is pointing -# to a commit that merges between the pull request and the upstream branch -# GITHUB_BASE_REF). - -set -euo pipefail - -UPSTREAM_BRANCH="${GITHUB_BASE_REF:-master}" -echo "Checking for incompatible API changes relative to ${UPSTREAM_BRANCH}..." - -MASTER_CLONE_DIR="$(mktemp -d)" -PKGINFO_BRANCH=$(mktemp) -PKGINFO_MASTER=$(mktemp) - -function cleanup() { - rm -f "$PKGINFO_BRANCH" "$PKGINFO_MASTER" -} -trap cleanup EXIT - -# Install apidiff. -go install golang.org/x/exp/cmd/apidiff@latest - -git clone -b "$UPSTREAM_BRANCH" . "$MASTER_CLONE_DIR" &> /dev/null - -# Run the following checks in the master directory -ORIG_DIR="$(pwd)" -cd "$MASTER_CLONE_DIR" - -incompatible_change_pkgs=() -while read -r path || [[ -n "$path" ]]; do - echo " checking packages in module $path" - pushd "$path" &> /dev/null - - PKGS=$(go list ./...) - for pkg in $PKGS; do - if [[ "$pkg" =~ "test" ]] || [[ "$pkg" =~ "internal" ]] || [[ "$pkg" =~ "samples" ]]; then - continue - fi - echo " checking ${pkg}..." - - # Compute export data for the current branch. - package_deleted=0 - (cd "$ORIG_DIR/$path" && apidiff -w "$PKGINFO_BRANCH" "$pkg") || package_deleted=1 - if [[ $package_deleted -eq 1 ]]; then - echo " package ${pkg} was deleted! Recording as an incompatible change."; - incompatible_change_pkgs+=("${pkg}"); - continue; - fi - - # Compute export data for master@HEAD. - apidiff -w "$PKGINFO_MASTER" "$pkg" - - # Print all changes for posterity. - apidiff "$PKGINFO_MASTER" "$PKGINFO_BRANCH" - - # Note if there's an incompatible change. - ic=$(apidiff -incompatible "$PKGINFO_MASTER" "$PKGINFO_BRANCH") - if [ -n "$ic" ]; then - incompatible_change_pkgs+=("$pkg"); - fi - done - popd &> /dev/null -done < <( sed -e '/^#/d' -e '/^$/d' allmodules | awk '{print $1}' ) - -if [ ${#incompatible_change_pkgs[@]} -eq 0 ]; then - # No incompatible changes, we are good. - echo "OK: No incompatible changes found." - exit 0; -fi -echo "Found breaking API change(s) in: ${incompatible_change_pkgs[*]}." - -# Found incompatible changes; see if they were declared as OK via a commit. -cd "$ORIG_DIR" -if git cherry -v master | grep -q "BREAKING_CHANGE_OK"; then - echo "Allowing them due to a commit message with BREAKING_CHANGE_OK."; - exit 0; -fi - -echo "FAIL. If this is expected and OK, you can pass this check by adding a commit with BREAKING_CHANGE_OK in the first line of the message." -exit 1 diff --git a/internal/testing/prerelease.sh b/internal/testing/prerelease.sh deleted file mode 100755 index d9c2d5b702..0000000000 --- a/internal/testing/prerelease.sh +++ /dev/null @@ -1,175 +0,0 @@ -#!/usr/bin/env bash -# Copyright 2019 The Go Cloud Development Kit Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# https://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# This script runs expensive checks that we don't normally run, but -# that should run periodically, before each release. -# For example, tests that can't use record/replay, so must be performed live -# against the backing service. -# -# It should be run from the root directory. - -# https://coderwall.com/p/fkfaqq/safer-bash-scripts-with-set-euxo-pipefail -# Change to -euxo if debugging. -set -euo pipefail - -function usage() { - echo - echo "Usage: prerelease.sh " 1>&2 - echo " init: creates any needed resources; rerun until it succeeds" - echo " run: runs all needed checks" - echo " cleanup: cleans up resources created in init" - exit 64 -} - -if [[ $# -ne 1 ]] ; then - echo "Need at least one argument." - usage -fi - -op="$1" -case "$op" in - init|run|cleanup);; - rerecord);; - *) echo "Unknown operation '$op'" && usage;; -esac - -# TODO: It would be nice to ensure that none of the tests are skipped. For now, -# we assume that if the "init" steps succeeded, the necessary tests will -# run. - -rootdir="$(pwd)" -FAILURES="" - -TESTDIR="mysql/azuremysql" -echo "***** $TESTDIR *****" -pushd "$TESTDIR" &> /dev/null -case "$op" in - init) - terraform init && terraform apply -var location="centralus" -var resourcegroup="GoCloud" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; - run) - go test -mod=readonly -race -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - terraform destroy -var location="centralus" -var resourcegroup="GoCloud" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; -esac -popd &> /dev/null - - -TESTDIR="mysql/gcpmysql" -echo -echo "***** $TESTDIR *****" -pushd "$TESTDIR" &> /dev/null -case "$op" in - init) - terraform init && terraform apply -var project="go-cloud-test-216917" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; - run) - go test -mod=readonly -race -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - terraform destroy -var project="go-cloud-test-216917" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; -esac -popd &> /dev/null - - -TESTDIR="mysql/awsmysql" -echo -echo "***** $TESTDIR *****" -pushd "$TESTDIR" &> /dev/null -case "$op" in - init) - terraform init && terraform apply -var region="us-west-1" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; - run) - go test -mod=readonly -race -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - terraform destroy -var region="us-west-1" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; -esac -popd &> /dev/null - - -TESTDIR="postgres/gcppostgres" -echo -echo "***** $TESTDIR *****" -pushd "$TESTDIR" &> /dev/null -case "$op" in - init) - terraform init && terraform apply -var project="go-cloud-test-216917" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; - run) - go test -mod=readonly -race -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - terraform destroy -var project="go-cloud-test-216917" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; -esac -popd &> /dev/null - - -TESTDIR="postgres/awspostgres" -echo -echo "***** $TESTDIR *****" -pushd "$TESTDIR" &> /dev/null -case "$op" in - init) - terraform init && terraform apply -var region="us-west-1" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; - run) - go test -mod=readonly -race -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - terraform destroy -var region="us-west-1" -auto-approve || FAILURES="$FAILURES $TESTDIR" - ;; -esac -popd &> /dev/null - - -# This iterates over all packages that have a "testdata" directory, using that -# as a signal for record/replay tests, and runs the tests with a "-record" flag. -# This verifies that we can generate a fresh recording against the live service. -while read -r TESTDIR; do - # Skip some packages that have a testdata/ dir but aren't record/replay. - if [ "$TESTDIR" == "./samples/order" ]; then - continue; - fi - echo - echo "***** $TESTDIR *****" - pushd "$TESTDIR" &> /dev/null - case "$op" in - init) - ;; - run|rerecord) - go test -mod=readonly -race -record -json | go run "$rootdir"/internal/testing/test-summary/test-summary.go -progress || FAILURES="$FAILURES $TESTDIR" - ;; - cleanup) - ;; - esac - popd &> /dev/null -done < <( find . -name testdata -printf "%h\\n" ) - -echo -echo -if [ ! -z "$FAILURES" ]; then - echo "FAILED!" - echo "Investigate and re-run -record tests for the following packages: $FAILURES" - exit 1 -fi - -echo "SUCCESS!" diff --git a/internal/testing/runchecks.sh b/internal/testing/runchecks.sh index e5f0d4a678..683db3affb 100755 --- a/internal/testing/runchecks.sh +++ b/internal/testing/runchecks.sh @@ -187,15 +187,6 @@ if [[ ${latest_go_version} -eq 1 ]]; then fi; -# For pull requests, check if there are undeclared incompatible API changes. -# Skip this if we're already going to fail since it is expensive. -# CURRENTLY BROKEN -# if [[ ${latest_go_version} -eq 1 ]] && [[ ${result} -eq 0 ]] && [[ ! -z "${GITHUB_HEAD_REF:-}" ]]; then - # echo - # ./internal/testing/check_api_change.sh || result=1; -# fi - - echo if [[ ${result} -eq 0 ]]; then echo "SUCCESS!"