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

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
-// current build is from a version greater that version. For example, v0.7-dev
-// means version > 0.7 and < 0.8. (There's exceptions to this rule, see
-// docs/releasing.md for more details.)
+// If you are looking at these fields in the git tree, they look
+// strange. They are modified on the fly by the build process. The
+// in-tree values are dummy values used for "git archive", which also
+// works for GitHub tar downloads.
 //
-// When releasing a new Kubernetes version, this file should be updated to
-// reflect the new version, and then a git annotated tag (using format vX.Y
-// where X == Major version and Y == Minor version) should be created to point
-// to the commit that updates pkg/version/base.go
-
+// When releasing a new Kubernetes version, this file is updated by
+// build/mark_new_version.sh to reflect the new version, and then a
+// git annotated tag (using format vX.Y where X == Major version and Y
+// == 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.
-	gitMajor     string = "1"              // major version, always numeric
-	gitMinor     string = "0.0+"           // minor version, numeric possibly followed by "+"
-	gitVersion   string = "v1.0.0-dev"     // version from git, output of $(git describe)
-	gitCommit    string = ""               // sha1 from git, output of $(git rev-parse HEAD)
+	// TODO: Deprecate gitMajor and gitMinor, use only gitVersion
+	// instead. First step in deprecation, keep the fields but make
+	// them irrelevant. (Next we'll take it out, which may muck with
+	// scripts consuming the kubectl version output - but most of
+	// 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"
 )