How to release

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
• Ensure the java-7 build is clean:
• mvn clean install -DjavaVersion=1.7 # switch local JDK to Java 7 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=-Xmx512m
mvn post-site site:stage -DstagingDirectory=/tmp/kite-stage -DtopSiteURL=http://kite-sdk.org
open /tmp/kite-stage/docs/*/index.html

• Check target/site/jdiff/missingSinces.txt for missing javadoc documentation and @since tags and fix anything that it reports.

Generate release notes

• 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 src/site/markdown/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=...
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 -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)

Publish the docs

export MAVEN_OPTS=-Xmx512m
export REMOTE=origin
git checkout release-$VERSION
mvn site-deploy
git checkout -b gh-pages $REMOTE/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 "Update 'current' link to $VERSION."
git push $REMOTE gh-pages
git checkout master

Then check in the jdiff files for the release:

• Copy and commit the jdiff XML file:

cp ./target/site/jdiff/*.xml ./src/jdiff/
git add src/jdiff
# Update `previous.project.version` in the top-level _pom.xml_ to be the new version number.
git commit -am "Update jdiff files."
git push $REMOTE master

Update kite-examples and associated integration tests

• Update the master branch:

# 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 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
find . -name pom.xml | xargs $SED "s|<kite-version>.*</kite-version>|<kite-version>$VERSION</kite-version>|"
git commit -am "Update stable examples for version $VERSION"
git push $REMOTE master
# build so the integration tests can run
for module in $(ls -d -- */); do
  (cd $module; mvn clean install)
done

• Create a new branch for the current version:

git checkout master
git checkout -b $VERSION
git push $REMOTE $VERSION

• Update the snapshot branch:

VERSION=... # e.g.,  # e.g., 0.10.1-SNAPSHOT
git checkout snapshot
git merge -X theirs master # merge all changes from master
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
find . -name pom.xml | xargs $SED "s|<kite-version>.*</kite-version>|<kite-version>$VERSION</kite-version>|"
git commit -am "Update snapshot examples for version $VERSION"
git push $REMOTE snapshot

• Update kite-examples-integration-tests for the new version and run against the QuickStart VM:

# in the kite-examples-integration-tests project
VERSION=... # e.g., 0.10.0
git checkout master
git merge -X theirs snapshot # merge all changes from snapshot
mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
# Edit all POMs that reference Kite to use the new, non-snapshot version
find . -name pom.xml | xargs $SED "s|<kite-version>.*</kite-version>|<kite-version>$VERSION</kite-version>|"
git diff
# run the tests (see instructions at https://github.com/kite-sdk/kite-examples-integration-tests)
mvn clean verify
git commit -am "Update to use version $VERSION artifacts."
git push $REMOTE master

• Update the snapshot branch too:

VERSION=... # e.g., 0.10.1-SNAPSHOT
git checkout snapshot
git merge -X theirs master # merge all changes from master
mvn versions:set -DnewVersion=$VERSION -DgenerateBackupPoms=false
# Edit all POMs that reference Kite to use the new, non-snapshot version
find . -name pom.xml | xargs $SED "s|<kite-version>.*</kite-version>|<kite-version>$VERSION</kite-version>|"
git diff
# run the tests (see instructions at https://github.com/kite-sdk/kite-examples-integration-tests)
mvn clean verify
git commit -am "Prepare for next development iteration $VERSION"
git push $REMOTE snapshot

Post-release sanity checks

• Run a sanity check such as trying one of the examples.

Post-release tasks

• In JIRA, under Manage Versions, click 'release' to show the version is released.

Announce the release

• Consult a previous release for an example.