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.
Hey folks,
I'd like to volunteer to be the release manager for a bug fix release of the
{{3.5 CHANGE ME!}} line. This will be the first bug fix release of this line and will be
version {{3.5.1 CHANGE ME!}}.
If no one has any objections, I will send out a release plan on {{DD-MM-YYYY}} that includes a list of all of the fixes we are targeting for
{{3.5.1 CHANGE ME!}} along with a timeline.
Thanks! |
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:
project = KAFKA AND fixVersion = 0.10.0.0 AND resolution = Unresolved AND priority = blocker ORDER BY due ASC, priority DESC, created ASC |
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 off 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.
sftp <your-apache-id>@home.apache.org`; if you get authentication failures, login to id.apache.org and add your public ssh key to your Apache account. If you need a new ssh key, generate one with `ssh-keygen -t rsa -b 4096 -C <your-apache-id>@apache.org` and saving the key in `~/.ssh/apache_rsa`, add the key locally with `ssh-add ~/.ssh/apache_rsa`, add the public SSH key (contents of `~/.ssh/apache_rsa.pub`) to your account using id.apache.org, and verify you can connect with sftp (may require up to 10 minutes for account changes to synchronize). See more detailed instructions.pip install jira=2.0.0 or newer.Host *.apache.org IdentityFile ~/.ssh/<apache-ssh-key> |
You will need to upload your maven credentials and signatory credentials for the release script by editing your `~/.gradle/gradle.properties` with:
mavenUrl=https://repository.apache.org/service/local/staging/deploy/maven2 mavenUsername=your-apache-id mavenPassword=your-apache-passwd signing.keyId=your-gpgkeyId # <- needs to be the 8-letter key ID signing.password=your-gpg-passphrase signing.secretKeyRingFile=/Users/your-id/.gnupg/secring.gpg |
If you don't already have a secret key ring under ~/.gnupg (which will be the case with GPG 2.1 and beyond), you will need to manually create it with `gpg --export-secret-keys -o ~/.gnupg/secring.gpg`. Obviously, be careful not to publicly upload your passwords. You should be editing the `gradle.properties` file under your home directory, not the one in Kafka itself.
Make sure your `~/.m2/settings.xml` is configured for pgp signing and uploading to the apache release maven:
<servers>
<server>
<id>apache.releases.https</id>
<username>your-apache-id</username>
<password>your-apache-passwd</password>
</server>
<server>
<id>your-gpgkeyId</id>
<passphrase>your-gpg-passphrase</passphrase>
</server>
</servers>
<profiles>
<profile>
<id>gpg-signing</id>
<properties>
<gpg.keyname>your-gpgkeyId</gpg.keyname>
<gpg.passphraseServerId>your-gpgkeyId</gpg.passphraseServerId>
</properties>
</profile>
</profiles> |
You may also need to update some gnupgp configs:
echo "allow-loopback-pinentry" >> ~/.gnupg/gpg-agent.conf echo "use-agent" >> ~/.gnupg/gpg.conf echo "pinentry-mode loopback" >> ~/.gnupg/gpg.conf echo RELOADAGENT | gpg-connect-agent |
Skip this section if you are releasing a bug fix version (e.g. 2.2.1).
gradle.properties
kafka-merge-pr.py
streams/quickstart/java/pom.xml
streams/quickstart/java/src/main/resources/archetype-resources/pom.xml
streams/quickstart/pom.xml
tests/kafkatest/__init__.py
tests/kafkatest/version.py (do not add the new release version, it will only be added after the release is completed)
Send email announcing the new branch:
To: dev@kafka.apache.org Subject: New release branch 0.10.0 Hello Kafka developers and friends, As promised, we now have a release branch for 0.10.0 release (with 0.10.0.0 as the version). Trunk has been bumped to 0.10.1.0-SNAPSHOT. I'll be going over the JIRAs to move every non-blocker from this release to the next release. From this point, most changes should go to trunk. *Blockers (existing and new that we discover while testing the release) will be double-committed. *Please discuss with your reviewer whether your PR should go to trunk or to trunk+release so they can merge accordingly. *Please help us test the release! * Thanks! $RM |
In between the branch cut and the RC cut, it's good to set up and keep an eye on the tests.
At the time of RC publishing, you will be asked to ensure you get a green run of integration tests & system tests. Due to flakes, this isn't always possible - so it's necessary to triage the tests & recognize what are flakes.
The earlier you do this, the easier it'll be later - hence this paragraph suggests you set them up now after the branch cut & start monitoring.
PUSH_REMOTE_NAME` to the remote you want to push to, e.g., export PUSH_REMOTE_NAME=origin (default is apache-github).~/.m2/settings.xml` or `~/.gradle/gradle.properties`$python3 release.py pip3 , for example $pip3 install jira – if pip can't find this, verify it's looking in the right repo by commenting out/removing any index-url settings in your ~/.pip/pip.conf apache/kafka - the image type you want is jvm.rc_tag is comprised of release version and rc version. For example apache/kafka:3.7.0-rc0 , can be the first RC docker image for 3.7.0 release.Note: Unlike the Kafka sources (kafka repo), the content of the Apache Kafka website kafka.apache.org is backed by a separate git repository (kafka-site repo). Today, any changes to the content and docs must be kept manually in sync between the two repositories.
We should improve the release script to include these steps. In the meantime, for new releases:
releaseTarGz generates the Kafka website content including the Kafka documentation (with the exception of a few pages like project-security.html, which are only tracked in the kafka-site repository). This build target also auto-generates the configuration docs of the Kafka broker/producer/consumer/etc. from their respective Java sources. The build output is stored in ./core/build/distributions/kafka_2.13-2.8.0-site-docs.tgz. site-docs/ folder to 28/ (or, if the latter already exists, replace its contents). That's because the docs for a release are stored in a separate folder (e.g., 27/ for Kafka v2.7 and 28/ for Kafka v2.8), which ensures the Kafka website includes the documentation for the current and all past Kafka releases.aggregatedJavadoc (`./gradlew aggregatedJavadoc`) on JDK 17, with output under ./build/docs/javadoc/.javadoc folder to 28/ (i.e., the full path is 28/javadoc/). If this is bug fix release, do this after the vote has passed to avoid showing an unreleased version number in the published javadocs.{RELEASE_VERSION}-SNAPSHOT. Once you have an RC cut with a git tag, check out that git tag and re-generate the javadocs. That way it will not have the -SNAPSHOT suffix anymoreIt's nice to thank as many people as we can identify. Please use "Find all contributors" script to generate the list of contributors.
- don't forget to bump the RC number.While waiting for the vote to pass, this is a good time to update the Collaborators (see https://github.com/apache/kafka-site/pull/510 for reference until the site update is published).
The process is documented in . If we complete that ticket, we can remove this step from the release process.
Send a vote closing email:
To: dev@kafka.apache.org, kafka-clients@googlegroups.com, users@kafka.apache.org Subject: [RESULTS] [VOTE] Release Kafka version 0.10.0.0 This vote passes with 7 +1 votes (3 bindings) and no 0 or -1 votes. +1 votes PMC Members: * $Name * $Name * $Name Committers: * $Name * $Name Community: * $Name * $Name 0 votes * No votes -1 votes * No votes Vote thread: http://markmail.org/message/faioizetvcils2zo I'll continue with the release process and the release announcement will follow in the next few days. $RM |
tests/kafkatest/version.py
Upload all artifacts, release notes, and docs (can be found in the .release_work_dir created by the release.py script) to https://dist.apache.org/repos/dist/release/kafka (a SVN repo, using Apache committer id/passwd).
| Note that only PMC members can upload to the `release` directory. If the RM is not in the PMC, they can upload the files to https://dist.apache.org/repos/dist/dev/kafka instead and ask a PMC member to move them to the release directory. |
Set your Apache username as environment variable
APACHE_USERNAME=<apache_username> |
Create a directory for the release. Assuming the release is 0.10.0.0:
svn mkdir --username $APACHE_USERNAME -m "Making directory for 0.10.0.0" https://dist.apache.org/repos/dist/release/kafka/0.10.0.0 |
Checkout the directory for the new release:
svn co --username $APACHE_USERNAME https://dist.apache.org/repos/dist/release/kafka/0.10.0.0 kafka-release-0-10-0-0 |
copy the release artifacts from the latest RC (the ones which were in your home.apache.org directory) to the new release directory, but exclude the `javadoc` directory since we don't publish that anymore to https://dist.apache.org/repos/dist/release/kafka
cd kafka-release-0-10-0-0 # note: there is a '~' sign in front of your APACHE_USERNAME # this step will take minutes wget --no-parent --recursive --reject "javadoc/*" "https://home.apache.org/~$APACHE_USERNAME/kafka-0.10.0.0-rc0/" mv "home.apache.org/~$APACHE_USERNAME/kafka-0.10.0.0-rc0/*" . rm -rf home.apache.org/ rm index.html* |
Add the files to SVN
svn --username $APACHE_USERNAME add * |
Commit the artifacts to subversion
svn commit --username $APACHE_USERNAME -m "Release 0.10.0.0" |
For PMC members only - If RM is a committer, you can move the artifacts from dev repo to release repo with the following commands. If RM is a PMC member, this step can be ignored.
# Set your env variable for apache username APACHE_USERNAME=<apache_username> # Create the directory for release in release repo svn mkdir --username $APACHE_USERNAME -m "Making directory for 0.10.0.0" https://dist.apache.org/repos/dist/release/kafka/0.10.0.0 # Checkout the directory for the new release svn co --username $APACHE_USERNAME https://dist.apache.org/repos/dist/release/kafka/0.10.0.0 kafka-release-0-10-0-0 # Copy the artifacts from dev repo to local svn co --username $APACHE_USERNAME https://dist.apache.org/repos/dist/dev/kafka/0.10.0.0 kafka-dev-0-10-0-0 # Move files from one folder into another mv kafka-dev-0-10-0-0/* kafka-release-0-10-0-0 # Add files to SVN and commit cd kafka-release-0-10-0-0 svn --username $APACHE_USERNAME add * svn commit --username $APACHE_USERNAME -m "Release 0.10.0.0" # Update the PGP KEYS cd svn co --username $APACHE_USERNAME --depth empty https://dist.apache.org/repos/dist/release/kafka/ kafka-pgp-0-10-0-0 cd kafka-pgp-0-10-0-0 svn update KEYS wget http://kafka.apache.org/KEYS mv KEYS.1 KEYS svn commit -m "Update PGP keys" |
apache/kafka:3.7.0-rc1 got voted and approved, it will be the RC docker image that needs to be used.apache/kafka:3.7.0 latest tag. Which means you need to run the above pipeline again and use promoted image as apache/kafka:latest Make sure to update the permissions on AWS S3 so they are readable by everyone
$ aws s3api put-object-acl --bucket kafka-packages --key kafka_2.13-3.0.0.tgz --acl public-read $ aws s3api put-object-acl --bucket kafka-packages --key kafka_2.12-3.0.0.tgz --acl public-read $ aws s3api put-object-acl --bucket kafka-packages --key kafka-streams-3.0.0-test.jar --acl public-read |
git grep "should always link the latest" | grep -v '^[0-9]'git grep -Irn -A1 "should always link the latest" | grep -v '^[0-9]' '<!--//#include virtual="'... to '<!--#include virtual="... . You can find the files by running git grep '<!--//#include virtual=' 
Server: mail-relay.apache.org Port: 587 (STARTTLS), 465 (SSL) User/Pass: {Your LDAP credentials}Check and update the Scala versions, if necessary, in the release email.
For feature releases, publish the blog post previously shared with the dev list.
After releasing the new version, we need to update the versions in the following files.
Here are some example PRs that update these files
It may also be worth tackling the compatibility/upgrade system tests as mentioned above.
Please file Jira tickets to remind teams to update their system tests (eg https://issues.apache.org/jira/browse/KAFKA-15672 – similar for others)
# The commands below assume that new version is 3.5.1 and last version is 3.5.
## set variables
CURRENT_RELEASE_TAG=3.5.1
OLD_RELEASE_TAG=3.5.0
## get list of contributors (commit authors and co-authors) sorted in alphabetical order and separated by comma
git shortlog -sn --group=author --group=trailer:co-authored-by --group=trailer:Reviewers --no-merges ${OLD_RELEASE_TAG}..${CURRENT_RELEASE_TAG} | cut -f2 | sort --ignore-case | uniq | sed -e ':a' -e '$!N;s/\n/, /;ta' -e 's/,$//' -e 's/%$//'
## get count of list of unique contributors
git shortlog -sn --group=author --group=trailer:co-authored-by --group=trailer:Reviewers --no-merges ${OLD_RELEASE_TAG}..${CURRENT_RELEASE_TAG} | cut -f2 | sort --ignore-case | uniq | wc -l |