Spruce up release instructions and release scripts (#2931)

* Update tag-release script

Signed-off-by: Carlisia <carlisia@vmware.com>

* Reorg release instructions

Signed-off-by: Carlisia <carlisia@vmware.com>

* Move "troubleshooting" to proper section

Signed-off-by: Carlisia <carlisia@vmware.com>

* Better formatting

Signed-off-by: Carlisia <carlisia@vmware.com>

* Fix sorcery

Signed-off-by: Carlisia <carlisia@vmware.com>

* Address code review

Signed-off-by: Carlisia <carlisia@vmware.com>

* More code reviews

Signed-off-by: Carlisia <carlisia@vmware.com>

hack/release-tools/chk_version.go

@@ -22,13 +22,13 @@ import (
 	"regexp"
 )
 
-// This regex should match both our GA format (example: v1.4.3) and pre-release format (v1.2.4-beta.2)
+// This regex should match both our GA format (example: v1.4.3) and pre-release formats (v1.2.4-beta.2, v1.5.0-rc.1)
 // The following sub-capture groups are defined:
 //	major
 //	minor
 //	patch
-//	prerelease (this will be alpha/beta followed by a ".", followed by 1 or more digits (alpha.5)
-var release_regex *regexp.Regexp = regexp.MustCompile("^v(?P<major>[[:digit:]]+)\\.(?P<minor>[[:digit:]]+)\\.(?P<patch>[[:digit:]]+)(-{1}(?P<prerelease>(alpha|beta)\\.[[:digit:]]+))*")
+//	prerelease (this will be alpha/beta/rc followed by a ".", followed by 1 or more digits (alpha.5)
+var release_regex *regexp.Regexp = regexp.MustCompile("^v(?P<major>[[:digit:]]+)\\.(?P<minor>[[:digit:]]+)\\.(?P<patch>[[:digit:]]+)(-{1}(?P<prerelease>(alpha|beta|rc)\\.[[:digit:]]+))*")
 
 // This small program exists because checking the VELERO_VERSION rules in bash is difficult, and difficult to test for correctness.
 // Calling it with --verify will verify whether or not the VELERO_VERSION environment variable is a valid version string, without parsing for its components.

hack/release-tools/gen-docs.sh

@@ -14,8 +14,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# gen-docs.sh is used for the "make gen-docs" target. See additional
-# documentation in the Makefile.
+# gen-docs.sh is used for the "make gen-docs" target. It generates a new 
+# versioned docs directory under site/content/docs. It follows
+# the following process:
+#   1. Copies the contents of the most recently tagged docs directory into the new
+#      directory, to establish a useful baseline to diff against.
+#   2. Adds all copied content from step 1 to git's staging area via 'git add'.
+#   3. Replaces the contents of the new docs directory with the contents of the
+#      'main' docs directory, updating any version-specific links (e.g. to a
+#      specific branch of the GitHub repository) to use the new version
+#   4. Copies the previous version's ToC file and runs 'git add' to establish
+#      a useful baseline to diff against.
+#   5. Replaces the content of the new ToC file with the main ToC.
+#   6. Update site/config.yaml and site/_data/toc-mapping.yml to include entries
+#      for the new version.
+#
+# The unstaged changes in the working directory can now easily be diff'ed against the
+# staged changes using 'git diff' to review all docs changes made since the previous 
+# tagged version. Once the unstaged changes are ready, they can be added to the
+# staging area using 'git add' and then committed.
+#
+# NEW_DOCS_VERSION defines the version that the docs will be tagged with 
+# (i.e. what’s in the URL, what shows up in the version dropdown on the site). 
+# This should be formatted as either v1.4 (for any GA release, including minor), or v1.5.0-beta.1/v1.5.0-rc.1 (for an alpha/beta/RC).
+
+# To run gen-docs: "VELERO_VERSION=v1.4.0 NEW_DOCS_VERSION=v1.4 PREVIOUS_DOCS_VERSION= make gen-docs"
+# Note: if PREVIOUS_DOCS_VERSION is not set, the script will copy from the 
+# latest version.
+#
+# **NOTE**: there are additional manual steps required to finalize the process of generating
+# a new versioned docs site. The full process is documented in site/README-HUGO.md
 
 set -o errexit
 set -o nounset

hack/release-tools/goreleaser.sh

@@ -36,14 +36,16 @@ else
     export GIT_TREE_STATE=dirty
 fi
 
-# $PUBLISH must explicitly be set to 'true' for goreleaser
+# $PUBLISH must explicitly be set to 'TRUE' for goreleaser
 # to publish the release to GitHub.
-if [[ "${PUBLISH:-}" != "true" ]]; then
+if [[ "${PUBLISH:-}" != "TRUE" ]]; then
+    echo "Not set to publish"
     goreleaser release \
         --rm-dist \
         --release-notes="${RELEASE_NOTES_FILE}" \
         --skip-publish
 else
+    echo "Getting ready to publish"
     goreleaser release \
         --rm-dist \
         --release-notes="${RELEASE_NOTES_FILE}"

hack/release-tools/tag-release.sh

@@ -15,9 +15,24 @@
 # limitations under the License.
 
 
-# This script will do the necessary checks and actions to create a release of Velero.
-# It will first validate that all prerequisites are met, then verify the version string is what the user expects.
-# A git tag will be created and pushed to GitHub, and GoReleaser will be invoked.
+# This script will do the necessary checks and actions to create a release of Velero. It will:
+# - validate that all prerequisites are met
+# - verify the version string is what the user expects.
+# - create a git tag
+# - push the created git tag to GitHub
+# - run GoReleaser
+
+# The following variables are needed:
+
+# - $VELERO_VERSION: defines the tag of Velero that any https://github.com/vmware-tanzu/velero/...
+#   links in the docs should redirect to.
+# - $publish: TRUE/FALSE value where FALSE (or not including it) will indicate a dry-run, and TRUE, or simply adding 'publish',
+#   will tag the release with the $VELERO_VERSION and push the tag to a remote named 'upstream'.
+# - $GITHUB_TOKEN: Needed to run the goreleaser process to generate a GitHub release. 
+#   Use https://github.com/settings/tokens/new?scopes=repo if you don't already have a token.
+#   Regenerate an existing token: https://github.com/settings/tokens.
+#   You may regenerate the token for every release if you prefer.
+#   See https://goreleaser.com/environment/ for more details.
 
 # This script is meant to be a combination of documentation and executable.
 # If you have questions at any point, please stop and ask!
@@ -26,7 +41,7 @@
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
 
 # Parse out the branch we're on so we can switch back to it at the end of a dry-run, where we delete the tag. Requires git v1.8.1+
-original_branch=$(git symbolic-ref --short HEAD)
+upstream_branch=$(git symbolic-ref --short HEAD)
 
 function tag_and_push() {
     echo "Tagging $VELERO_VERSION"
@@ -76,6 +91,7 @@ printf "Based on this, the following assumptions have been made: \n"
 
 [[ "$VELERO_PATCH" != 0 ]] && printf "*\t This is a patch release.\n"
 
+# $VELERO_PRERELEASE gets populated by the chk_version.go script that parses and verifies the given version format 
 # -n is "string is non-empty"
 [[ -n $VELERO_PRERELEASE ]] && printf "*\t This is a pre-release.\n"
 
@@ -97,6 +113,7 @@ echo "Alright, let's go."
 echo "Pulling down all git tags and branches before doing any work."
 git fetch upstream --tags
 
+# $VELERO_PATCH gets populated by the chk_version.go scrip that parses and verifies the given version format 
 # If we've got a patch release, we'll need to create a release branch for it.
 if [[ "$VELERO_PATCH" > 0 ]]; then
     release_branch_name=release-$VELERO_MAJOR.$VELERO_MINOR
@@ -114,7 +131,7 @@ if [[ "$VELERO_PATCH" > 0 ]]; then
     echo "Now you'll need to cherry-pick any relevant git commits into this release branch."
     echo "Either pause this script with ctrl-z, or open a new terminal window and do the cherry-picking."
     if [[ $publish == "TRUE" ]]; then
-        read -p "Press enter when you're done cherry-picking. THIS WILL MAKE A TAG PUSH THE BRANCH TO UPSTREAM"
+        read -p "Press enter when you're done cherry-picking. THIS WILL MAKE A TAG PUSH THE BRANCH TO upstream"
     else
         read -p "Press enter when you're done cherry-picking."
     fi
@@ -144,7 +161,7 @@ if [[ $publish == "FALSE" ]]; then
     # Delete the local tag so we don't potentially conflict when it's re-run for real.
     # This also means we won't have to just ignore existing tags in tag_and_push, which could be a problem if there's an existing tag.
     echo "Dry run complete. Deleting git tag $VELERO_VERSION"
-    git checkout $original_branch
+    git checkout $upstream_branch
     git tag -d $VELERO_VERSION
 fi