Committer Release Guide
This page contains instructions for Pulsar committers on how to perform a release for the Pulsar C++ client.
Open a discussion in [email protected] to notify others that you volunteer to be the release manager of a specific release. If there are no disagreements, you can start the release process.
For major releases, you should create a new branch named branch-3.X once all PRs with the 3.X.0 milestone are merged. If some PRs with the 3.X.0 milestone are still working in progress and might take much time to complete, you can move them to the next milestone if they are not important. In this case, you'd better notify the author in the PR.
For minor releases, if there are no disagreements, you should cherry-pick all merged PRs with the release/X.Y.Z labels into branch-X.Y. After these PRs are cherry-picked, you should add the cherry-picked/branch-X.Y labels.
Sometimes some PRs cannot be cherry-picked cleanly, you might need to create a separate PR and move the release/X.Y.Z label from the original PR to it. In this case, you can ask the author to help create the new PR.
For PRs that are still open, you can choose to delay them to the next release or ping others to review so that they can be merged.
If you haven't already done it, create and publish the GPG key to sign the release artifacts.
We are going to create a branch from main to branch-3.X where the tag will be generated and where new fixes will be applied as part of the maintenance for the release.
The branch needs only to be created when creating major releases, and not for minor releases like 3.3.1. For minor releases, go to the next step.
For example, when you create the v3.3.0 release, the branch branch-3.3 will be created; but for v3.3.1, we
keep using the old branch-3.3.
In these instructions, I'm referring to a fictitious release 3.X.0. Change the release version in the examples accordingly with the real version.
It will also be assumed to have a Git remote repository named apache for the official repo [email protected]:apache/pulsar-client-cpp.git.
cd pulsar-client-cpp
git checkout -b branch-3.X apache/mainDuring the release process, you are going to initially create "candidate" tags, that after verification and approval will get promoted to the "real" final tag.
In this process, the maven version of the project will always be the final one.
Edit version.txt to contain the new release version 3.x.0.
# Commit the change
git commit -m 'Release 3.X.0' -a
# Create a "candidate" tag
# If you don't sign your commits already, use the following
export GPG_TTY=$(tty)
git tag -u $USER@apache.org v3.X.0-candidate-1 -m 'Release v3.X.0-candidate-1'
# If you already sign your commits using your apache.org email, use the following
git tag -s v3.X.0-candidate-1 -m 'Release v3.X.0-candidate-1'
# Verify that you signed your tag before pushing it:
git tag -v v3.X.0-candidate-1Follow the README to build the library locally.
git push origin branch-3.X
git push origin v3.X.0-candidate-1For minor releases, the tag is like 3.3.1.
When the build is pushed to the Apache repo, a Github action job will run and build all the binary artifacts.
The build will be available at https://github.com/apache/pulsar-client-cpp/actions
Once the workflow is completed (ETA ~30 min), the artifacts will be available for download.
Record the id of the workflow as WORKFLOW_ID.
All the artifacts need to be signed and uploaded to the dist SVN repository for staging.
Before running the script, make sure that the [email protected] code signing key is the default gpg signing key.
One way to ensure this is to create/edit file ~/.gnupg/gpg.conf and add a line
default-key <key fingerprint>
where <key fingerprint> should be replaced with the private key fingerprint for the [email protected] key. The key fingerprint can be found in gpg -K output.
svn co https://dist.apache.org/repos/dist/dev/pulsar/pulsar-client-cpp/ pulsar-dist-dev
cd pulsar-dist-dev
# '-candidate-1' needs to be incremented in case of multiple iterations in getting
# to the final release)
svn mkdir pulsar-client-cpp-3.X.0-candidate-1
cd pulsar-3.X.0-candidate-1
# Generate token from here: https://github.com/settings/tokens
export GITHUB_TOKEN=${Your GitHub token}
$PULSAR_PATH/build-support/stage-release.sh . $WORKFLOW_ID
svn add *
svn ci -m 'Staging artifacts and signature for Pulsar Client C++ release 3.X.0'After that, open PRs in pulsar-client-python and pulsar-client-node to make sure the candidate does not bring any regression, see https://github.com/apache/pulsar-client-cpp/wiki/Verify-the-candidate-release-in-your-local-env#verify-the-3rd-party-projects-that-depend-on-pulsar-c-client
Send an email to the Pulsar Dev mailing list:
To: [email protected]
Subject: [VOTE] Pulsar Client C++ Release 3.X.0 Candidate 1
This is the first release candidate for Apache Pulsar Client C++, version 3.X.0.
It fixes the following issues:
https://github.com/apache/pulsar-client-cpp/milestone/8?closed=1
*** Please download, test and vote on this release. This vote will stay open
for at least 72 hours ***
Note that we are voting upon the source (tag), binaries are provided for
convenience.
Source and binary files:
https://dist.apache.org/repos/dist/dev/pulsar/pulsar-client-cpp/pulsar-client-cpp-3.X.0-candidate-1/
SHA-512 checksums:
f7cc55137281d5257e3c8127e1bc7016408834b1 apache-pulsar-client-cpp-3.x.0.tar.gz
The tag to be voted upon:
v3.X.0-candidate-1 (21f4a4cffefaa9391b79d79a7849da9c539af834)
https://github.com/apache/pulsar-client-cpp/releases/tag/v3.X.0-candidate-1
Pulsar's KEYS file containing PGP keys you use to sign the release:
https://downloads.apache.org/pulsar/KEYS
Please download the source package, and follow
https://github.com/apache/pulsar-client-cpp/wiki/Verify-the-candidate-release-in-your-local-env
to compile and test.
Note: If you're going to run the unit tests locally, please make sure the proxy is disabled.
The vote should be open for at least 72 hours (3 days). Votes from Pulsar PMC members will be considered binding, while anyone else is encouraged to verify the release and vote as well.
If the release is approved here, you can then proceed to the next step. Otherwise, you should repeat the previous steps and prepare another candidate release to vote.
NOTE: This step is for major releases only.
You need to move the master version to the next iteration Y (X + 1).
git checkout main
# Edit version.txt and commit
git commit -m 'Bumped version to 3.Y.0-pre' -aSince this needs to be merged into main, you need to follow the regular process
and create a Pull Request on GitHub.
Create the final git tag:
git tag -u $USER@apache.org v3.X.0 -m 'Release v3.X.0'
git push apache v3.X.0Promote the artifacts on the release location(repo https://dist.apache.org/repos/dist/release limited to PMC, You may need a PMC member's help if you are not one):
svn move -m "Release Apache Pulsar Client C++ 3.X.Y" \
https://dist.apache.org/repos/dist/dev/pulsar/pulsar-client-cpp/pulsar-client-cpp-3.X.0-candidate-1 \
https://dist.apache.org/repos/dist/release/pulsar/pulsar-client-cpp-3.X.0This step should be skipped if the major version number is not the latest.
Release a new version of libpulsar for Homebrew, You can follow the example here.
NOTE: This step is for major releases only.
To generate C++ client docs, run the following script from the apache/pulsar-site main branch:
cd pulsar-site
git checkout -b gen-cpp-apidoc
cd tools/pytools
poetry install
poetry run bin/cpp-apidoc-generator.py 3.X.Y Read pytool's README for more information.
Once the docs are generated, you can add them and submit them in a PR. The expected doc output is static/api/cpp.
Add release notes to the Github release page (https://github.com/apache/pulsar-client-cpp/releases)
You can click the Generate release notes button to generate the release notes automatically. Before clicking that button, you need to choose the tag and the previous tag properly.
For minor releases, you can run the following command to generate the content of the "What's Changed" section:
gh pr list -L 200 --search "is:pr is:closed label:release/3.X.Y" \
--json title,url,author \
| jq '.[] | "* \(.title) by @\(.author.login) in \(.url)"' \
| sed 's/^"\(.*\)"$/\1/'Note:
Use the
release/3.X.Ylabel instead ofmilestone:3.X.Yfor minor releases
You should also submit the release notes via a PR to the pulsar-site repo. For example, https://github.com/apache/pulsar-site/pull/419
Once the release artifacts are available in the Apache Mirrors and the website is updated, we need to announce the release.
Send an email to these lines:
To: [email protected], [email protected], [email protected]
Subject: [ANNOUNCE] Apache Pulsar Client C++ 3.X.0 released
The Apache Pulsar team is proud to announce Apache Pulsar Client C++ version 3.X.0.
Pulsar is a highly scalable, low latency messaging platform running on
commodity hardware. It provides simple pub-sub semantics over topics,
guaranteed at-least-once delivery of messages, automatic cursor management for
subscribers, and cross-datacenter replication.
For Pulsar release details and downloads, visit:
https://pulsar.apache.org/download/#pulsar-c-client
Release Notes are at:
https://pulsar.apache.org/release-notes/client-cpp
API documents are at:
https://pulsar.apache.org/api/cpp/3.X.x/index.html
We would like to thank the contributors that made the release possible.
Regards,
The Pulsar Team
Send the email in plain text mode since the [email protected] mailing list will reject messages with text/html content.
In Gmail, there's an option to set Plain text mode in the ⋮/ More options menu.