Skip to content

How to release

Jump to bottom
Tom White edited this page Feb 12, 2015 · 54 revisions

This page documents how to make a Kite release. Pre-requisites:

  • You must have sent an email to the list saying when the release is planned for and when committers should stop committing to the master branch.
  • You must have run through all of the Kite examples manually.
  • You must have the correct credentials to commit to the Kite repo and Kite examples repo from the command line. (This GitHub article about SSH issues has some useful advice if you are getting an error.)
  • You must have the necessary credentials in ~/.m2/settings.xml to deploy artifacts to the Sonatype OSSRH repository, which are automatically synced with Maven Central.
  • You must have a public GPG key. See this ASF document for guidance.
  • You must add your GitHub credentials to ~/.m2/settings.xml to deploy the site documentation to GitHub pages (more details):
<server>
  <id>github</id>
  <password>YOUR-OAUTH2-TOKEN</password>
</server>

Pre-release sanity checks

  • Ensure the CI builds are clean:
  • Check the latest Travis CI builds for master or build locally with:
    • mvn clean install
    • mvn clean install -Dhadoop.profile=1 -Dthrift.version=0.9.0 # see CDK-357 for why we need thrift.version
  • If you have access, check the internal Cloudera CI Kite jobs are all passing
  • Ensure the java-6 build is clean:
  • Check the latest Java 6 Jenkins builds or build locally with:
    • mvn clean install -DjavaVersion=1.6 # switch local JDK to Java 6 first
  • Check that there are no Javadoc warnings: http://sandbox.jenkins.cloudera.com/job/kite/warnings28/trendDetails/
  • Check that previous.project.version in the top-level pom.xml is the version of the previous release.
  • Generate the site documentation locally and read it through. Is anything missing (e.g. new features)? If so, then add more documentation. Are there any new packages that we shouldn't be publishing Javadoc for?
export MAVEN_OPTS=-Xmx1g
mvn post-site site:stage -DstagingDirectory=/tmp/kite-stage -DtopSiteURL=http://kite-sdk.org
open /tmp/kite-stage/docs/*/apidocs/index.html
  • Check target/site/jdiff/missingSinces.txt for missing javadoc documentation and @since tags and fix anything that it reports.

Generate release notes

  • File a Task in JIRA for the release. You'll reference this JIRA number in release commits.
  • In JIRA, create a new release version for the release after the one you are doing.
  • If there are any open issues against the release, then fix them or push them to the next release.
  • Update kite-docs/release-notes.md with a section for the new release describing the high-level changes.
  • Push all your changes.

Do the release

  • We use the Maven release plugin.
  • First do a dry run to check everything is working. You will be prompted for the SCM release tag, and the new development version - the defaults should be correct. If you don't have gpg-agent then you can pass your passphrase in using -Darguments="-Dgpg.passphrase=XXX" to avoid having to enter it for each artifact.
export VERSION=...
export COMMIT_PREFIX="CDK-XXX:"
mvn release:prepare -DreleaseVersion=$VERSION -DdryRun=true -Prelease
  • If the dry run worked, then prepare the release. The tests can be skipped if they passed during the dry run.
mvn release:clean release:prepare -DscmCommentPrefix="$COMMIT_PREFIX " -DreleaseVersion=$VERSION -Prelease -Darguments="-DskipTests"
  • Perform the release - this will deploy the artifacts to Maven.
mvn release:perform -Prelease -Darguments="-DskipTests"
  • Note that if anything fails you can rollback with mvn release:rollback, although this does not delete tags in the repo, so you should delete these manually.
  • If you need to run the dry run more than once and know the tests are passing, you can skip the tests using -Darguments="-DskipTests" (source)
  • Log in to https://oss.sonatype.org/#stagingRepositories and make a note of the URL of your staging repository.

Publish the docs

Before you publish the docs, be sure that you've checked out the kite-docs project and you can build it according to the README instructions.

In the Kite repository, check in the jdiff files for the release:

  • Copy and commit the jdiff XML file:
git checkout master
cp /tmp/kite-stage/docs/$VERSION/jdiff/*.xml ./src/jdiff/
git add src/jdiff
vi pom.xml # Update `previous.project.version` in the top-level _pom.xml_ to be the new version number.
git commit -am "${COMMIT_PREFIX} Update jdiff files."
git push $REMOTE master

Update kite-examples

  • Create a new branch for the current version:
# in the kite-examples project
SED="sed -i ''" # on Linux omit argument after -i: "sed -i"
VERSION=... # e.g., 0.10.0
git checkout master
git checkout -b $VERSION
git merge -X theirs snapshot # merge all changes from snapshot
for module in $(ls -d -- */); do
  (cd $module; mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false)
done
# Edit all POMs that reference Kite to use the current version, unfortunately we can't use mvn versions:update-parent since the version isn't in Maven central yet
SNAPSHOT_VERSION=... # e.g. 0.9.1-SNAPSHOT
find . -name pom.xml | xargs $SED "s|<version>$SNAPSHOT_VERSION</version>|<version>$VERSION</version>|"
# run the integration tests
for module in $(ls -d -- */); do
  (cd $module; mvn clean verify; if [ $? -ne 0 ]; then break; fi)
done
git commit -am "${COMMIT_PREFIX} Update stable examples for version $VERSION"
git push $REMOTE $VERSION
  • Update the snapshot branch:
NEW_VERSION=... # e.g., 0.10.1-SNAPSHOT
git checkout snapshot
git merge -X theirs $VERSION # merge all changes from master
for module in $(ls -d -- */); do
  (cd $module; mvn versions:set -DnewVersion=$NEW_VERSION -DgenerateBackupPoms=false)
done
# Edit all POMs that reference Kite to use the current version
find . -name pom.xml | xargs $SED "s|<version>$VERSION</version>|<version>$NEW_VERSION</version>|"
git commit -am "${COMMIT_PREFIX} Update snapshot examples for version $NEW_VERSION"
git push $REMOTE snapshot

Post-release sanity checks

  • This is a good chance to send an email to the mailing list saying that the release has been staged (include the staging URL of the Maven repo), so folks can check it if they like.
  • Run a sanity check such as trying one of the examples.

Synchronize with Maven Central

Post-release tasks

  • Update current docs link to point to the new release:
export VERSION=...
export REMOTE=origin
git checkout gh-pages
git pull $REMOTE gh-pages
rm -rf docs/current
cp -r docs/$VERSION docs/current
git add --all docs/current
git commit -am "${COMMIT_PREFIX} Update 'current' link to $VERSION."
git push $REMOTE gh-pages
git checkout master
  • Update the master branches for kite-examples
export VERSION=...
git checkout master
git reset --hard $VERSION
git push $REMOTE master
  • In JIRA, under Manage Versions, click 'release' to show the version is released.

Announce the release

  • Consult a previous release for an example.
Clone this wiki locally