This document describes how to release Apache Kafka from trunk.
It is a work in progress and should be refined by the Release Manager (RM) as they come across aspects of the release process not yet documented here.
NOTE: For the purpose of illustration, this document assumes that the version being released is 0.10.0.0 and the following development version will become 0.10.1.0.
- Prepare release plan in the wiki, notifying the community the overall plan and goals for the release (For example: Release Plan 0.10.0)
Vote on release plan: Release manager should start a vote in email@example.com, asking the community to approve the release plan.
Go over JIRA for the release and make sure that blockers are marked as blockers and non-blockers are non-blockers. This JIRA filter may be handy:
It is important that between the time that the release plan is voted to the time when the release branch is created, no experimental or potentially destabilizing work is checked into the trunk. While it is acceptable to introduce major changes, they must be thoroughly reviewed and have good test coverage to ensure that the release branch does not start of being unstable. If necessary the RM can discuss if certain issues should be fixed on the trunk in this time, and if so what is the gating criteria for accepting them.
- Make sure you are working with a clean repo (i.e. identical to upstream - no changes in progress). If needed clone a fresh copy
- git checkout trunk
- Check that current HEAD points to commit on which you want to base new release branch. Checkout particular commit if not.
- git branch 0.10.0
- git push apache 0.10.0
- Check that the branch was correctly propagated to Apache using the webui: https://git-wip-us.apache.org/repos/asf?p=kafka.git
- Modify the version in trunk to bump to the next one "0.10.1.0-SNAPSHOT" in gradle.properties, tests/kafkatest/__init__.py and kafka-merge-pr.py. Commit and push to trunk in apache.
- Create new Jenkins Build job that validates the new branch (Java 7 is enough)
Send email announcing the new branch:
Create Release Artifacts
Create a release tag - because our release branch is still 0.10.0.0-SNAPSHOT but our release artifact needs to be 0.10.0.0, we'll make the change in a tag:
- Modify the version in 0.10.0 branch to remove "-SNAPSHOT" in gradle.properties, tests/kafkatest/__init__.py and kafka-merge-pr.py. Commit locally, but don't push to Apache.
- Prepare an RC tag:
git tag -a 0.10.0.0-rc0 (this will tag the version change commit, get the rc part to match the actual rc number)
Move the branch head back, so future commits will still have "-SNAPSHOT"
- git reset --hard HEAD~1
- Push the tag to Apache:
- git push --tags
Prepare a workspace:
git clone https://git-wip-us.apache.org/repos/asf/kafka.git kafka
git checkout -b 0.10.0 tags/0.10.0.0-rc0 <- important! checkout the tag, or you'll be releasing SNAPSHOT accidentally.
Prepare a public release staging area:
- The easiest way is to sftp them over to home.apache.org/public_html using your apache id (in sftp, first create kafka-0.10.0.0-candidate1, then put -r localDir kafka-0.10.0.0-candidate1).
Check NOTICE and LICENSE files
- Make sure the NOTICE file has the correct year
Prepare release notes
- Go to JIRA, move all unresolved jiras with "Fix versions" of 0.9.0.0 to future releases.
- Select roadmap from left panel, click on "release notes" next to the release version and prepare/format the html release notes. The html version shows up at the bottom of the page. Save the release notes as RELEAE_NOTES.html
Upload the release notes to home.apache.org
Now make sure the log commit is the same of the tag you are sending out and that you checked out
- cd ..
- mkdir kafka-0.9.0.0-src
- cd kafka-0.9.0.0-src
- cp -r ../kafka/* .
- git status
fatal: Not a git repository (or any of the parent directories): .git
- if you did not get this you messed up somewhere please go back.
Now prepare the source (after getting your keys local to the box)
- cd ..
- tar -zcvf kafka-0.9.0.0-src.tgz kafka-0.9.0.0-src/
sign the artifact
( gpg --armor --output kafka-0.9.0.0-src.tgz.asc --detach-sig kafka-0.9.0.0-src.tgz
gpg --print-md MD5 kafka-0.9.0.0-src.tgz > kafka-0.9.0.0-src.tgz.md5
gpg --print-md SHA1 kafka-0.9.0.0-src.tgz > kafka-0.9.0.0-src.tgz.sha1
gpg --print-md SHA512 kafka-0.9.0.0-src.tgz > kafka-0.9.0.0-src.tgz.sha2 )
- upload the artifacts to where you are staging them
- check they are there
Validate the signatures:
- download the files you signed and uploaded
- gpg --verify kafka-0.10.0.0-src.tgz.asc kafka-0.10.0.0-src.tgz
You should see valid signatures and no errors, continue.
- make sure your java is on jdk 1.7 (On mac: export JAVA_HOME=$(/usr/libexec/java_home -v 1.7))
Make sure you have Gradle installed
- cd kafka-0.9.0.0-src
- ./gradlew clean releaseTarGzAll
- cd core/build/distributions/
- sign the artifacts:
for file in *.tgz; do gpg --armor --output $file.asc --detach-sig $file; done
for file in *.tgz; do gpg --verify $file.asc $file; done
for file in *.tgz; do gpg --print-md md5 $file > $file.md5; done
for file in *.tgz; do gpg --print-md sha1 $file > $file.sha1; done
for file in *.tgz; do gpg --print-md sha512 $file > $file.sha2; done
Prepare java and scala docs.
- copy the javadoc and scaladoc directories over
Make sure all the binary artifacts, release notes, java and scala doc are exposed through your home.apache.org URL.
Go drop whatever staging repository may be in the maven repo
- If you haven't set up gpg key, set up one using 4096 bit RSA (http://www.apache.org/dev/release-signing.html). Make sure that your public key is uploaded to one of the public servers (http://www.apache.org/dev/release-signing.html#keyserver). Also, add your public key to https://github.com/apache/kafka-site/blob/asf-site/KEYS
- Set up ~/.gradle.properties like the following. Make sure that you can login to https://repository.apache.org/ with your apache id/passwd. The value for signing.keyId can be found by running "gpg --list-secret-keys --fingerprint". The number after the / in the first line is your signing.keyId.
- ./gradlew uploadArchivesAll
- Go to https://repository.apache.org/#stagingRepositories, find the uploaded artifacts and close the staging repository (don't promote until the vote passes). The artifacts should show up under https://repository.apache.org/content/groups/staging/.
Website update process:
For new releases:
- Make sure the documentation (docs/documentation.html, docs/quickstart.html,docs/api.html) are all referring to the correct release and links.
- Git clone https://git-wip-us.apache.org/repos/asf/kafka-site.git
- checkout the branch asf-site
- The releaseTarGzAll target should auto-generate the configuration docs for broker/producer/consumer in ./core/build/distributions/kafka_2.10-0.9.0.0-site-docs.tgz. Untar the file in 090/.
- Copy release javadoc to newly 090/.
- Update documentation.html to include the new documentation link (090/documentation.html).
- Update protocol.html to include the new protocol guide link (090/protocol.html).
- Update downloads.html to include the new download links from mirrors and change last release to use archive.
- Mark the version as released in Kafka JIRA (from JIRA administration panel, select versions and scroll mouse towards the end of the line for the particular version. From the dropdown list, select release and set the date).
Send out a voting email to firstname.lastname@example.org, email@example.com, firstname.lastname@example.org. In the email, include the git revision next to the git tag (since tag will be dropped when rolling out a new RC).
Verification for voting:
gpg --import KEYS (KEYS can be obtained from http://kafka.apache.org/KEYS)
- gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
- Test at least quickstart and unit tests for all scala versions.
If need to roll a new RC
- Go to https://repository.apache.org/#stagingRepositories, find the uploaded artifacts and drop it.
- Go back to the beginning - don't forget to bump the RC number.
After the vote passes:
- Remember: at least 3 days, 3 +1 from PMC members (committers are not enough!) and no -1.
- Merge the last version change / rc tag into the release branch
- Update version on the branch to 0.10.0.1
Send a vote closing email:
- Upload all artifacts, release notes, and docs to https://dist.apache.org/repos/dist/release/kafka (an svn repo, using Apache committer id/passwd)
- Go to https://repository.apache.org/#stagingRepositories, find the uploaded artifacts and release this (this will push to maven central)
- Wait for about a day for the artifacts to show up in apache mirror and maven central.
- Send out an announcement email. You will need to use your apache email address to send out the email (otherwise, it won't be delivered to email@example.com).
- Log into people.apache.org with your apache id.
- Include a paragraph in the announcement email like: "According to git shortlog <number_of_contributors> people contributed to this release: <contributors>" where:
- number_of_contributors is determined via `git shortlog -sn --no-merges <previous_release_tag>..<current_release_tag> | wc -l` (eg `git shortlog -sn --no-merges 0.8.2.2..0.9.0.0 | wc -l`)
- contributors is determined via: `git shortlog -sn --no-merges <previous_release_tag>..<current_release_tag> | cut -f2 | tr '\n' ',' | sed -e 's/,/, /g'` (eg `git shortlog -sn --no-merges 0.8.2.2..0.9.0.0 | cut -f2 | sort --ignore-case | tr '\n' ',' | sed -e 's/,/, /g'`)
- cat mail.txt|mail -s "[ANNOUCE] ..." firstname.lastname@example.org, email@example.com, firstname.lastname@example.org, email@example.com
- Add the release data to https://reporter.apache.org/addrelease.html?kafka (must be a Kafka PMC member)