Fixups of docs and scripts

build/build-official-release.sh

@@ -88,29 +88,31 @@ ln -s ${KUBE_BUILD_DIR}/_output/release-tars/kubernetes.tar.gz ${KUBE_BUILD_DIR}
 MD5=$(md5 "${KUBE_BUILD_DIR}/kubernetes.tar.gz")
 SHA1=$(sha1 "${KUBE_BUILD_DIR}/kubernetes.tar.gz")
 
-echo ""
+echo <<- EOM
-echo "Success! You must now do the following: (you may want to cut"
+
-echo "  and paste these instructions elsewhere, step 1 can be spammy)"
+Success! You must now do the following: (you may want to cut
-echo ""
+  and paste these instructions elsewhere, step 1 can be spammy)
-echo "  1) (cd ${KUBE_BUILD_DIR}; build/push-official-release.sh ${KUBE_RELEASE_VERSION})"
+
-echo "  2) Go to https://github.com/GoogleCloudPlatform/kubernetes/releases"
+  1) (cd ${KUBE_BUILD_DIR}; build/push-official-release.sh ${KUBE_RELEASE_VERSION})
-echo "     and create a new 'Release ${KUBE_RELEASE_VERSION} Candidate' release"
+  2) Go to https://github.com/GoogleCloudPlatform/kubernetes/releases
-echo "     with the ${KUBE_RELEASE_VERSION} tag. Mark it as a pre-release."
+     and create a new 'Release ${KUBE_RELEASE_VERSION} Candidate' release
-echo "  3) Upload the ${KUBE_BUILD_DIR}/kubernetes.tar.gz to GitHub"
+     with the ${KUBE_RELEASE_VERSION} tag. Mark it as a pre-release.
-echo "  4) Use this template for the release:"
+  3) Upload the ${KUBE_BUILD_DIR}/kubernetes.tar.gz to GitHub
-echo ""
+  4) Use this template for the release:
-echo "## [Documentation](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/docs/README.md)"
+
-echo "## [Examples](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/examples)"
+## [Documentation](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/docs/README.md)
-echo "## Changes since <last release> (last PR <last PR>)"
+## [Examples](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/examples)
-echo ""
+## Changes since <last release> (last PR <last PR>)
-echo "<release notes>"
+
-echo ""
+<release notes>
-echo "binary | hash alg | hash"
+
-echo "------ | -------- | ----"
+binary | hash alg | hash
-echo "\`kubernetes.tar.gz\` | md5 | \`${MD5}\`"
+------ | -------- | ----
-echo "\`kubernetes.tar.gz\` | sha1 | \`${SHA1}\`"
+\`kubernetes.tar.gz\` | md5 | \`${MD5}\`
-echo ""
+\`kubernetes.tar.gz\` | sha1 | \`${SHA1}\`
-echo "     We'll fill in the release notes in the next stage."
+
-echo "  5) Ensure all the binaries are in place on GitHub and GCS before cleaning."
+     We'll fill in the release notes in the next stage.
-echo "  6) (cd ${KUBE_BUILD_DIR}; make clean; cd -; rm -rf ${KUBE_BUILD_DIR})"
+  5) Ensure all the binaries are in place on GitHub and GCS before cleaning.
-echo ""
+  6) (cd ${KUBE_BUILD_DIR}; make clean; cd -; rm -rf ${KUBE_BUILD_DIR})
+
+EOM

build/cut-official-release.sh

@@ -113,18 +113,20 @@ EOM
   pushd "${DIR}"
 
   if [[ "${release_type}" == 'alpha' ]]; then
+    local -r ancestor="v${version_major}.${version_minor}.0-alpha.$((${version_alpha_rev}-1))"
     git checkout "${git_commit}"
     verify-at-git-commit "${git_commit}"
-    verify-ancestor "v${version_major}.${version_minor}.0-alpha.$((${version_alpha_rev}-1))"
+    verify-ancestor "${ancestor}"
 
     alpha-release "${new_version}"
   elif [[ "${release_type}" == 'official' ]]; then
     local -r release_branch="release-${version_major}.${version_minor}"
     local -r beta_version="v${version_major}.${version_minor}.$((${version_patch}+1))-beta"
+    local -r ancestor="${new_version}-beta"
 
     git checkout "${release_branch}"
     verify-at-git-commit "${git_commit}"
-    verify-ancestor "${new_version}-beta"
+    verify-ancestor "${ancestor}"
 
     official-release "${new_version}"
     beta-release "${beta_version}"
@@ -132,14 +134,15 @@ EOM
     local -r release_branch="release-${version_major}.${version_minor}"
     local -r alpha_version="v${version_major}.$((${version_minor}+1)).0-alpha.0"
     local -r beta_version="v${version_major}.${version_minor}.0-beta"
-
-    git checkout "${git_commit}"
-    verify-at-git-commit "${git_commit}"
     # NOTE: We check the second alpha version, ...-alpha.1, because ...-alpha.0
     # is the branch point for the previous release cycle, so could provide a
     # false positive if we accidentally try to release off of the old release
     # branch.
-    verify-ancestor "v${version_major}.${version_minor}.0-alpha.1"
+    local -r ancestor="v${version_major}.${version_minor}.0-alpha.1"
+
+    git checkout "${git_commit}"
+    verify-at-git-commit "${git_commit}"
+    verify-ancestor "${ancestor}"
 
     alpha-release "${alpha_version}"
 
@@ -179,7 +182,18 @@ function alpha-release() {
   echo "Tagging ${alpha_version} at $(current-git-commit)."
   git tag -a -m "Kubernetes pre-release ${alpha_version}" "${alpha_version}"
   git-push "${alpha_version}"
-  finish-release-instructions "${alpha_version}"
+
+  cat >> "${INSTRUCTIONS}" <<- EOM
+- Finish the ${alpha_version} release build:
+  - From this directory (clone of upstream/master),
+      ./release/build-official-release.sh ${alpha_version}
+  - Figure out what the PR numbers for this release and last release are, and
+    get an api-token from GitHub (https://github.com/settings/tokens).  From a
+    clone of kubernetes/contrib at upstream/master,
+      go run release-notes/release-notes.go --last-release-pr=<number> --current-release-pr=<number> --api-token=<token>
+    Feel free to prune, but typically for patch releases we tend to include
+    everything in the release notes.
+EOM
 }
 
 function beta-release() {
@@ -193,7 +207,10 @@ function beta-release() {
   echo "Tagging ${beta_version} at $(current-git-commit)."
   git tag -a -m "Kubernetes pre-release ${beta_version}" "${beta_version}"
   git-push "${beta_version}"
-  finish-release-instructions "${beta_version}"
+
+  # NOTE: We currently don't build/release beta versions, since they're almost
+  # identical to the prior version, so we don't prompt for build or release
+  # here.
 }
 
 function official-release() {
@@ -207,7 +224,21 @@ function official-release() {
   echo "Tagging ${official_version} at $(current-git-commit)."
   git tag -a -m "Kubernetes release ${official_version}" "${official_version}"
   git-push "${official_version}"
-  finish-release-instructions "${official_version}"
+
+  cat >> "${INSTRUCTIONS}" <<- EOM
+- Finish the ${version} release build:
+  - From this directory (clone of upstream/master),
+      ./release/build-official-release.sh ${version}
+  - Prep release notes:
+    - From this directory (clone of upstream/master), run
+        ./hack/cherry_pick_list.sh ${version}
+      to get the release notes for the patch release you just created. Feel
+      free to prune anything internal, but typically for patch releases we tend
+      to include everything in the release notes.
+    - If this is a first official release (vX.Y.0), scan through the release
+      notes for all of the alpha releases since the last cycle, and include
+      anything important in release notes.
+EOM
 }
 
 function verify-at-git-commit() {
@@ -284,13 +315,4 @@ function git-push() {
   fi
 }
 
-function finish-release-instructions() {
-  local -r version="${1}"
-
-  cat >> "${INSTRUCTIONS}" <<- EOM
-- Finish the ${version} release build:
-    ./build/build-official-release.sh ${version}
-EOM
-}
-
 main "$@"

docs/design/versioning.md

@@ -53,7 +53,7 @@ There is no mandated timeline for major versions. They only occur when we need t
 
 ### CI version scheme
 
-* Continuous integration versions also exist, and are versioned off of alpha and beta releases.  X.Y.Z-alpha.W.C+aaaa is C commits after X.Y.Z-alpha.W, with an additional +aaaa build suffix added; X.Y.Z-beta.C+bbbb is C commits after X.Y.Z-beta, with an additional +bbbb build suffix added.
+* Continuous integration versions also exist, and are versioned off of alpha and beta releases.  X.Y.Z-alpha.W.C+aaaa is C commits after X.Y.Z-alpha.W, with an additional +aaaa build suffix added; X.Y.Z-beta.C+bbbb is C commits after X.Y.Z-beta, with an additional +bbbb build suffix added.  Furthermore, builds that are built off of a dirty build tree, (with things in the tree that are not checked it,) it will be appended with -dirty.
 
 ## Release versions as related to API versions
 

docs/devel/releasing.md

@@ -78,9 +78,16 @@ No matter what you're cutting, you're going to want to look at
 (see above,) and look at the critical jobs building from that branch.  First
 glance through builds and look for nice solid rows of green builds, and then
 check temporally with the other critical builds to make sure they're solid
-around then as well. Once you find some greens, you can find the git hash for a
+around then as well.
-build by looking at the Full Console Output and searching for `githash=`. You
+
-should see a line:
+If you're doing an alpha release or cutting a new release series, you can
+choose an arbitrary build.  If you are doing an official release, you have to
+release from HEAD of the branch, (because you have to do some version-rev
+commits,) so choose the latest build on the release branch.  (Remember, that
+branch should be frozen.)
+
+Once you find some greens, you can find the git hash for a build by looking at
+the Full Console Output and searching for `githash=`. You should see a line:
 
 ```console
 githash=v1.2.0-alpha.2.164+b44c7d79d6c9bb
@@ -115,10 +122,12 @@ will become your release point.
 You'll need the latest version of the releasing tools:
 
 ```console
-git clone git@github.com:kubernetes/contrib.git
+git clone git@github.com:kubernetes/kubernetes.git
-cd contrib/release
+cd kubernetes
 ```
 
+or `git checkout upstream/master` from an existing repo.
+
 #### Cutting an alpha release (`vX.Y.0-alpha.W`)
 
 Figure out what version you're cutting, and
@@ -127,10 +136,10 @@ Figure out what version you're cutting, and
 export VER="vX.Y.0-alpha.W"
 ```
 
-then, from `contrib/release`, run
+then, run
 
 ```console
-cut.sh "${VER}" "${GITHASH}"
+build/cut-official-release.sh "${VER}" "${GITHASH}"
 ```
 
 This will:
@@ -147,10 +156,10 @@ Figure out what version you're cutting, and
 export VER="vX.Y.Z"
 ```
 
-then, from `contrib/release`, run
+then, run
 
 ```console
-cut.sh "${VER}" "${GITHASH}"
+build/cut-official-release.sh "${VER}" "${GITHASH}"
 ```
 
 This will:
@@ -161,7 +170,7 @@ This will:
 1. do a series of commits on the branch for `vX.Y.(Z+1)-beta` on top of the
    previous commits, including versionizing the documentation and doing the
    beta version commit;
-1. mark the `vX.Y.(Z+1)-beta` tag at the release version commit;
+1. mark the `vX.Y.(Z+1)-beta` tag at the beta version commit;
 1. prompt you to do the remainder of the work, including building the
    appropriate binaries and pushing them to the appropriate places.
 
@@ -177,10 +186,10 @@ Figure out what series you're cutting, and
 export VER="vX.Y"
 ```
 
-then, from `contrib/release`, run
+then, run
 
 ```console
-cut.sh "${VER}" "${GITHASH}"
+build/cut-official-release.sh "${VER}" "${GITHASH}"
 ```
 
 This will:
@@ -189,18 +198,19 @@ This will:
 1. fork a new branch `release-X.Y` off of `master` at the given git hash;
 1. do a series of commits on the branch for `vX.Y.0-beta`, including versionizing
    the documentation and doing the release version commit;
-1. mark the `vX.Y.(Z+1)-beta` tag at the beta version commit;
+1. mark the `vX.Y.0-beta` tag at the beta version commit;
 1. prompt you to do the remainder of the work, including building the
    appropriate binaries and pushing them to the appropriate places.
 
 ### Publishing binaries and release notes
 
-Whichever script you ran above will prompt you to take any remaining steps,
+The script you ran above will prompt you to take any remaining steps, including
-including publishing binaries and release notes.
+publishing binaries and release notes.
 
-## Origin of the Sources
+## Injecting Version into Binaries
 
-TODO(ihmccreery) update this
+*Please note that this information may be out of date.  The scripts are the
+authoritative source on how version injection works.*
 
 Kubernetes may be built from either a git tree (using `hack/build-go.sh`) or
 from a tarball (using either `hack/build-go.sh` or `go install`) or directly by
@@ -216,36 +226,6 @@ access to the information about the git tree, but we still want to be able to
 tell whether this build corresponds to an exact release (e.g. v0.3) or is
 between releases (e.g. at some point in development between v0.3 and v0.4).
 
-## Version Number Format
-
-TODO(ihmccreery) update everything below here
-
-In order to account for these use cases, there are some specific formats that
-may end up representing the Kubernetes version. Here are a few examples:
-
-- **v0.5**: This is official version 0.5 and this version will only be used
-  when building from a clean git tree at the v0.5 git tag, or from a tree
-  extracted from the tarball corresponding to that specific release.
-- **v0.5-15-g0123abcd4567**: This is the `git describe` output and it indicates
-  that we are 15 commits past the v0.5 release and that the SHA1 of the commit
-  where the binaries were built was `0123abcd4567`. It is only possible to have
-  this level of detail in the version information when building from git, not
-  when building from a tarball.
-- **v0.5-15-g0123abcd4567-dirty** or **v0.5-dirty**: The extra `-dirty` prefix
-  means that the tree had local modifications or untracked files at the time of
-  the build, so there's no guarantee that the source code matches exactly the
-  state of the tree at the `0123abcd4567` commit or at the `v0.5` git tag
-  (resp.)
-- **v0.5-dev**: This means we are building from a tarball or using `go get` or,
-  if we have a git tree, we are using `go install` directly, so it is not
-  possible to inject the git version into the build information. Additionally,
-  this is not an official release, so the `-dev` prefix indicates that the
-  version we are building is after `v0.5` but before `v0.6`. (There is actually
-  an exception where a commit with `v0.5-dev` is not present on `v0.6`, see
-  later for details.)
-
-## Injecting Version into Binaries
-
 In order to cover the different build cases, we start by providing information
 that can be used when using only Go build tools or when we do not have the git
 version information available.
@@ -276,22 +256,6 @@ can, for instance, tell it to override `gitVersion` and set it to
 `v0.4-13-g4567bcdef6789-dirty` and set `gitCommit` to `4567bcdef6789...` which
 is the complete SHA1 of the (dirty) tree used at build time.
 
-## Release Notes
-
-TODO(ihmccreery) update this
-
-No official release should be made final without properly matching release notes.
-
-There should be made available, per release, a small summary, preamble, of the
-major changes, both in terms of feature improvements/bug fixes and notes about
-functional feature changes (if any) regarding the previous released version so
-that the BOM regarding updating to it gets as obvious and trouble free as possible.
-
-After this summary, preamble, all the relevant PRs/issues that got in that
-version should be listed and linked together with a small summary understandable
-by plain mortals (in a perfect world PR/issue's title would be enough but often
-it is just too cryptic/geeky/domain-specific that it isn't).
-
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/releasing.md?pixel)]()