diff --git a/build/build-official-release.sh b/build/build-official-release.sh index 8db1957ea4f..176b32cb33f 100755 --- a/build/build-official-release.sh +++ b/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 "Success! You must now do the following: (you may want to cut" -echo " and paste these instructions elsewhere, step 1 can be spammy)" -echo "" -echo " 1) (cd ${KUBE_BUILD_DIR}; build/push-official-release.sh ${KUBE_RELEASE_VERSION})" -echo " 2) Go to https://github.com/GoogleCloudPlatform/kubernetes/releases" -echo " and create a new 'Release ${KUBE_RELEASE_VERSION} Candidate' release" -echo " with the ${KUBE_RELEASE_VERSION} tag. Mark it as a pre-release." -echo " 3) Upload the ${KUBE_BUILD_DIR}/kubernetes.tar.gz to GitHub" -echo " 4) Use this template for the release:" -echo "" -echo "## [Documentation](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/docs/README.md)" -echo "## [Examples](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/examples)" -echo "## Changes since (last PR )" -echo "" -echo "" -echo "" -echo "binary | hash alg | hash" -echo "------ | -------- | ----" -echo "\`kubernetes.tar.gz\` | md5 | \`${MD5}\`" -echo "\`kubernetes.tar.gz\` | sha1 | \`${SHA1}\`" -echo "" -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." -echo " 6) (cd ${KUBE_BUILD_DIR}; make clean; cd -; rm -rf ${KUBE_BUILD_DIR})" -echo "" +echo <<- EOM + +Success! You must now do the following: (you may want to cut + and paste these instructions elsewhere, step 1 can be spammy) + + 1) (cd ${KUBE_BUILD_DIR}; build/push-official-release.sh ${KUBE_RELEASE_VERSION}) + 2) Go to https://github.com/GoogleCloudPlatform/kubernetes/releases + and create a new 'Release ${KUBE_RELEASE_VERSION} Candidate' release + with the ${KUBE_RELEASE_VERSION} tag. Mark it as a pre-release. + 3) Upload the ${KUBE_BUILD_DIR}/kubernetes.tar.gz to GitHub + 4) Use this template for the release: + +## [Documentation](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/docs/README.md) +## [Examples](http://releases.k8s.io/${KUBE_RELEASE_VERSION}/examples) +## Changes since (last PR ) + + + +binary | hash alg | hash +------ | -------- | ---- +\`kubernetes.tar.gz\` | md5 | \`${MD5}\` +\`kubernetes.tar.gz\` | sha1 | \`${SHA1}\` + + We'll fill in the release notes in the next stage. + 5) Ensure all the binaries are in place on GitHub and GCS before cleaning. + 6) (cd ${KUBE_BUILD_DIR}; make clean; cd -; rm -rf ${KUBE_BUILD_DIR}) + +EOM diff --git a/release/cut.sh b/build/cut-official-release.sh similarity index 84% rename from release/cut.sh rename to build/cut-official-release.sh index 1312076129b..328f90027fa 100755 --- a/release/cut.sh +++ b/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= --current-release-pr= --api-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 "$@" diff --git a/docs/design/versioning.md b/docs/design/versioning.md index 75cdffce80d..a189d0cfa49 100644 --- a/docs/design/versioning.md +++ b/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 diff --git a/docs/devel/releasing.md b/docs/devel/releasing.md index 971c2878edd..2ba88bd3357 100644 --- a/docs/devel/releasing.md +++ b/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 -build by looking at the Full Console Output and searching for `githash=`. You -should see a line: +around then as well. + +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 -cd contrib/release +git clone git@github.com:kubernetes/kubernetes.git +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, -including publishing binaries and release notes. +The script you ran above will prompt you to take any remaining steps, including +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). - [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/releasing.md?pixel)]()