Enacting versioning.md

This PR changes how we version going forward in the following ways:

* mark-new-version.sh is changed to a new policy of just splitting
branches, rather than the old backmerge policy, as discussed in
vX.Y.0, and a tag for vX.(Y+1).0-alpha.0 back to master.

* I eliminated PRs back to master by making the version/base.go
gitVersion and gitCommit just be `export-subst`. I testing that this
works with GitHub's source export tarballs. There's no reason to
bother with forcing the version into `base.go` (especially twice). The
tarball versions outside a git tree aren't perfect (master looks like
"v0.0.0+hash", and the release branches look more accurate), but our
build contract has never allowed that version is perfect in this
situation, so I think we can relax this.

* That master tag gets picked up by "git describe" on master, so e.g.
master would have immediately become v1.1.0-alpha.0

* In order to be more semVer compatible, the gitVersion field for the
master branch now looks something like 1.1.0-alpha.0.6+84c76d1142ea4d.
This is a tiny translation of the "git describe". I did this because
there are a ton of consumers out there of the "gitVersion" field
expecting it to be the full version, but it would be nice if this
field were actually semver compliant. (1.1.0-alpha.0-6-84c76d1142ea4d
is, but it's not *usefully* so.)

Fixes #11495

build/mark-new-version.sh

@@ -52,6 +52,7 @@ fi
 
 release_branch="release-${VERSION_MAJOR}.${VERSION_MINOR}"
 current_branch=$(git rev-parse --abbrev-ref HEAD)
+head_commit=$(git rev-parse --short HEAD)
 
 if [[ "${VERSION_PATCH}" != "0" ]]; then
   # sorry, no going back in time, pull latest from upstream
@@ -93,15 +94,13 @@ echo "+++ Running ./versionize-docs"
 ${KUBE_ROOT}/build/versionize-docs.sh ${NEW_VERSION}
 git commit -am "Versioning docs and examples for ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}"
 
-dochash=$(git log -n1 --format=%H)
-
 VERSION_FILE="${KUBE_ROOT}/pkg/version/base.go"
 
 GIT_MINOR="${VERSION_MINOR}.${VERSION_PATCH}"
 echo "+++ Updating to ${NEW_VERSION}"
 $SED -ri -e "s/gitMajor\s+string = \"[^\"]*\"/gitMajor string = \"${VERSION_MAJOR}\"/" "${VERSION_FILE}"
 $SED -ri -e "s/gitMinor\s+string = \"[^\"]*\"/gitMinor string = \"${GIT_MINOR}\"/" "${VERSION_FILE}"
-$SED -ri -e "s/gitVersion\s+string = \"[^\"]*\"/gitVersion string = \"$NEW_VERSION\"/" "${VERSION_FILE}"
+$SED -ri -e "s/gitVersion\s+string = \"[^\"]*\"/gitVersion string = \"$NEW_VERSION-${release_branch}+\$Format:%h\$\"/" "${VERSION_FILE}"
 gofmt -s -w "${VERSION_FILE}"
 
 echo "+++ Committing version change"
@@ -110,35 +109,30 @@ git commit -m "Kubernetes version $NEW_VERSION"
 
 echo "+++ Tagging version"
 git tag -a -m "Kubernetes version $NEW_VERSION" "${NEW_VERSION}"
+newtag=$(git rev-parse --short HEAD)
 
-echo "+++ Updating to ${NEW_VERSION}-dev"
+if [[ "${VERSION_PATCH}" == "0" ]]; then
-$SED -ri -e "s/gitMajor\s+string = \"[^\"]*\"/gitMajor string = \"${VERSION_MAJOR}\"/" "${VERSION_FILE}"
+  declare -r alpha_ver="v${VERSION_MAJOR}.$((${VERSION_MINOR}+1)).0-alpha.0"
-$SED -ri -e "s/gitMinor\s+string = \"[^\"]*\"/gitMinor string = \"${GIT_MINOR}\+\"/" "${VERSION_FILE}"
+  git tag -a -m "Kubernetes pre-release branch ${alpha-ver}" "${alpha_ver}" "${head_commit}"
-$SED -ri -e "s/gitVersion\s+string = \"[^\"]*\"/gitVersion string = \"$NEW_VERSION-dev\"/" "${VERSION_FILE}"
+fi
-gofmt -s -w "${VERSION_FILE}"
-
-echo "+++ Committing version change"
-git add "${VERSION_FILE}"
-git commit -m "Kubernetes version ${NEW_VERSION}-dev"
 
 echo ""
 echo "Success you must now:"
 echo ""
 echo "- Push the tag:"
 echo "   git push ${push_url} v${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH}"
-echo "   - Please note you are pushing the tag live BEFORE your PRs."
-echo "       You need this so the builds pick up the right tag info (and so your reviewers can see it)."
-echo "       If something goes wrong further down please fix the tag!"
-echo "       Either delete this tag and give up, fix the tag before your next PR,"
-echo "       or find someone who can help solve the tag problem!"
-echo ""
 
 if [[ "${VERSION_PATCH}" == "0" ]]; then
-  echo "- Send branch: ${current_branch} as a PR to ${push_url}/master"
+  echo "- Push the alpha tag:"
-  echo "   For major/minor releases, this gets the branch tag merged and changes the version numbers."
+  echo "   git push ${push_url} ${alpha_ver}"
   echo "- Push the new release branch:"
   echo "   git push ${push_url} ${current_branch}:${release_branch}"
+  echo "- DO NOTHING TO MASTER. You were done with master when you pushed the alpha tag."
 else
   echo "- Send branch: ${current_branch} as a PR to ${release_branch} <-- NOTE THIS"
-  echo "  Get someone to review and merge that PR"
+  echo "- In the contents of the PR, include the PRs in the release:"
+  echo "    hack/cherry_pick_list.sh ${current_branch}^1"
+  echo "  This helps cross-link PRs to patch releases they're part of in GitHub."
+  echo "- Have someone review the PR. This is a mechanical review to ensure it contains"
+  echo "  the ${NEW_VERSION} commit, which was tagged at ${newtag}."
 fi

hack/lib/version.sh

@@ -50,6 +50,13 @@ kube::version::get_version_vars() {
 
     # Use git describe to find the version based on annotated tags.
     if [[ -n ${KUBE_GIT_VERSION-} ]] || KUBE_GIT_VERSION=$("${git[@]}" describe --tags --abbrev=14 "${KUBE_GIT_COMMIT}^{commit}" 2>/dev/null); then
+      # This translates the "git describe" to an actual semver.org
+      # compatible semantic version that looks something like this:
+      #   v1.1.0-alpha.0.6+84c76d1142ea4d
+      #
+      # TODO: We continue calling this "git version" because so many
+      # downstream consumers are expecting it there.
+      KUBE_GIT_VERSION=$(echo "${KUBE_GIT_VERSION}" | sed "s/-\([0-9]\{1,\}\)-g\([0-9a-f]\{14\}\)$/.\1\+\2/")
       if [[ "${KUBE_GIT_TREE_STATE}" == "dirty" ]]; then
         # git describe --dirty only considers changes to existing files, but
         # that is problematic since new untracked .go files affect the build,
@@ -57,6 +64,7 @@ kube::version::get_version_vars() {
         KUBE_GIT_VERSION+="-dirty"
       fi
 
+
       # Try to match the "git describe" output to a regex to try to extract
       # the "major" and "minor" versions and whether this is the exact tagged
       # version or whether the tree is between two tagged versions.

pkg/version/.gitattributes

@@ -0,0 +1 @@
+base.go export-subst

pkg/version/base.go

@@ -23,21 +23,35 @@ package version
 // version for ad-hoc builds (e.g. `go build`) that cannot get the version
 // information from git.
 //
-// The "-dev" suffix in the version info indicates that fact, and it means the
+// If you are looking at these fields in the git tree, they look
-// current build is from a version greater that version. For example, v0.7-dev
+// strange. They are modified on the fly by the build process. The
-// means version > 0.7 and < 0.8. (There's exceptions to this rule, see
+// in-tree values are dummy values used for "git archive", which also
-// docs/releasing.md for more details.)
+// works for GitHub tar downloads.
 //
-// When releasing a new Kubernetes version, this file should be updated to
+// When releasing a new Kubernetes version, this file is updated by
-// reflect the new version, and then a git annotated tag (using format vX.Y
+// build/mark_new_version.sh to reflect the new version, and then a
-// where X == Major version and Y == Minor version) should be created to point
+// git annotated tag (using format vX.Y where X == Major version and Y
-// to the commit that updates pkg/version/base.go
+// == Minor version) is created to point to the commit that updates
-
+// pkg/version/base.go
 var (
-	// TODO: Deprecate gitMajor and gitMinor, use only gitVersion instead.
+	// TODO: Deprecate gitMajor and gitMinor, use only gitVersion
-	gitMajor     string = "1"              // major version, always numeric
+	// instead. First step in deprecation, keep the fields but make
-	gitMinor     string = "0.0+"           // minor version, numeric possibly followed by "+"
+	// them irrelevant. (Next we'll take it out, which may muck with
-	gitVersion   string = "v1.0.0-dev"     // version from git, output of $(git describe)
+	// scripts consuming the kubectl version output - but most of
-	gitCommit    string = ""               // sha1 from git, output of $(git rev-parse HEAD)
+	// these should be looking at gitVersion already anyways.)
+	gitMajor string = "" // major version, always numeric
+	gitMinor string = "" // minor version, numeric possibly followed by "+"
+
+	// semantic version, dervied by build scripts (see
+	// https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/versioning.md
+	// for a detailed discussion of this field)
+	//
+	// TODO: This field is still called "gitVersion" for legacy
+	// reasons. For prerelease versions, the build metadata on the
+	// semantic version is a git hash, but the version itself is no
+	// longer the direct output of "git describe", but a slight
+	// translation to be semver compliant.
+	gitVersion   string = "v0.0.0-master+$Format:%h$"
+	gitCommit    string = "$Format:%H$"    // sha1 from git, output of $(git rev-parse HEAD)
 	gitTreeState string = "not a git tree" // state of git tree, either "clean" or "dirty"
 )