Skip to content

Commit

Permalink
Fixups of docs and scripts
Browse files Browse the repository at this point in the history
  • Loading branch information
Isaac Hollander McCreery committed Nov 2, 2015
1 parent 1b00825 commit f2b8edd
Show file tree
Hide file tree
Showing 4 changed files with 96 additions and 108 deletions.
54 changes: 28 additions & 26 deletions build/build-official-release.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 release> (last PR <last PR>)"
echo ""
echo "<release notes>"
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 release> (last PR <last PR>)
<release notes>
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
58 changes: 40 additions & 18 deletions release/cut.sh → build/cut-official-release.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -113,33 +113,36 @@ 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}"
else # [[ "${release_type}" == 'series' ]]
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}"

Expand Down Expand Up @@ -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() {
Expand All @@ -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() {
Expand All @@ -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() {
Expand Down Expand Up @@ -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 "$@"
2 changes: 1 addition & 1 deletion docs/design/versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
90 changes: 27 additions & 63 deletions docs/devel/releasing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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.

Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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)]()
Expand Down

0 comments on commit f2b8edd

Please sign in to comment.