This page contains instructions for Pulsar committers on how to perform a release for the Pulsar Python client.
Bump up the version number as follows.
If you haven't already done it, create and publish the GPG key to sign the release artifacts.
Before running the commands in the following sections, make sure the GPG_TTY environment variable has been set.
export GPG_TTY=$(tty)
During the development, the C++ client dependency might be downloaded from an unofficial release. But when releasing the Python client, the dependency must be downloaded from an official release. You should modify the base url in dep-url.sh.
Example: https://github.com/apache/pulsar-client-python/pull/62
After all necessary PRs are cherry-picked to branch-X.Y, you should cut the release by pushing a tag.
For major and minor releases (X.Y.0), you need to create a new branch:
git checkout -b branch-X.Y perl -pi -e "s/__version__.*/__version__='X.Y.Z'/" pulsar/__about__.py git add pulsar/__about__.py git commit -m "Bump version to X.Y.0" git push origin branch-X.Y # N starts with 1 git tag -u $USER@apache.org vX.Y.0-candidate-N -m "Release vX.Y.0 candidate N" git push origin vX.Y.0-candidate-N
For patch releases (X.Y.Z), you need to reuse the existing branch:
git checkout branch-X.Y perl -pi -e "s/__version__.*/__version__='X.Y.Z'/" pulsar/__about__.py git add pulsar/__about__.py git commit -m "Bump version to X.Y.Z" git push origin branch-X.Y # N starts with 1 git tag -u $USER@apache.org vX.Y.Z-candidate-N -m "Release vX.Y.Z candidate N" git push origin vX.Y.Z-candidate-N
Then, create a new milestone for the next major release.
After a tag is pushed, a workflow will be triggered to build the Python wheels in GitHub Actions. You can find it in https://github.com/apache/pulsar-client-python/actions/workflows/ci-build-release-wheels.yaml
For example, https://github.com/apache/pulsar-client-python/actions/runs/3709463737 is the workflow of v3.0.0-candidate-3, the workflow id is 3709463737. Remember the workflow id, which will be passed as an argument of stage-release.sh in the following step. Once the workflow is completed, the wheels will be available for downloading.
Generate a GitHub token by following the guide here. The repo and workflow checkboxes must be selected. Then export the token as the environment variable:
export GITHUB_TOKEN=<your-token>
Edit ~/.gnupg/gpg.conf to ensure the default GPG key is from your Apache mail (<your-name>@apache.org):
default-key <key fingerprint>
Make sure curl, jq, unzip, gpg, shasum commands are available. Then you should run the following commands in an empty directory:
svn co https://dist.apache.org/repos/dist/dev/pulsar pulsar-dist-dev-keys --depth empty cd pulsar-dist-dev-keys svn mkdir pulsar-client-python-X.Y.Z-candidate-N && cd pulsar-client-python-X.Y.Z-candidate-N # PROJECT_DIR is the directory of the pulsar-client-python repository $PROJECT_DIR/build-support/stage-release.sh X.Y.Z-candidate-N $WORKFLOW_ID svn add * svn ci -m "Staging artifacts and signature for Python client X.Y.Z-candidate-N"
Send an email to dev@pulsar.apache.org to start the vote for the candidate:
To: dev@pulsar.apache.org Subject: [VOTE] Pulsar Client Python Release X.Y.Z Candidate N This is the Nth release candidate for Apache Pulsar Client Python, version X.Y.Z. It fixes the following issues: https://github.com/apache/pulsar-client-python/milestone/<milestone-id>?closed=1 *** Please download, test and vote on this release. This vote will stay open for at least 72 hours *** Python wheels: https://dist.apache.org/repos/dist/dev/pulsar/pulsar-client-python-X.Y.Z-candidate-N/ The supported python versions are 3.8, 3.9, 3.10, 3.11 and 3.12. The supported platforms and architectures are: - Windows x86_64 (windows/) - glibc-based Linux x86_64 (linux-glibc-x86_64/) - glibc-based Linux arm64 (linux-glibc-arm64/) - musl-based Linux x86_64 (linux-musl-x86_64/) - musl-based Linux arm64 (linux-musl-arm64/) - macOS universal 2 (macos/) You can download the wheel (the `.whl` file) according to your own OS and Python version and install the wheel: - Windows: `py -m pip install *.whl --force-reinstall` - Linux or macOS: `python3 -m pip install *.whl --force-reinstall` The tag to be voted upon: vX.Y.Z-candidate-N (<commit-id>) https://github.com/apache/pulsar-client-python/releases/tag/vX.Y.Z-candidate-N Pulsar's KEYS file containing PGP keys you use to sign the release: https://downloads.apache.org/pulsar/KEYS Please download the Python wheels and follow the README to test.
Once there are at least 3 binding +1s, the vote will be ready to close and you can continue the following steps. If there is something wrong with the candidate, you need to fix it and repeat the steps from the Cut the next candidate section again.
You need to move the main version to the next iteration.
git checkout main perl -pi -e "s/X.Y.0a1/X.Y+1.0a1/" pulsar/__about__.py git add pulsar/__about__.py git commit -m "Bumped version to X.Y.0a1"
Since this needs to be merged into main, you need to follow the regular process and create a Pull Request on GitHub.
Ask a PMC member to promote the release:
svn move -m "Release Apache Pulsar Client Python X.Y.Z" \ https://dist.apache.org/repos/dist/dev/pulsar/pulsar-client-python-X.Y.Z-candidate-N \ https://dist.apache.org/repos/dist/release/pulsar/pulsar-client-python-X.Y.Z
Then, upload the wheels to PyPI:
sudo python3 -m pip install twine ./build-support/upload-pypi.sh https://dist.apache.org/repos/dist/release/pulsar/pulsar-client-python-X.Y.Z
To sign in to PyPI, please use __token__ as your username and enter your API token as the password.
To verify the wheels have been uploaded successfully, you can try installing the wheel:
python3 -m pip install pulsar-client==X.Y.Z
Push the official tag:
git checkout vX.Y.Z-candidate-N git tag -u $USER@apache.org vX.Y.Z -m "Release vX.Y.Z" git push origin vX.Y.Z
Then, create a release. Choose the vX.Y.Z tag and click the Generate release notes button to generate the release note automatically. Here is an example release note: https://github.com/apache/pulsar-client-python/releases/tag/v3.0.0
Then, create a PR in pulsar-site repo to update the website. Here is an example: https://github.com/apache/pulsar-site/pull/761
For minor releases, skip this section. For major releases, you should generate the HTML files into the pulsar-site repo:
# Use the first two version numbers, e.g. export VERSION=3.2 VERSION=X.Y # You need to install the wheel to have the _pulsar.so installed # It's better to run the following commands in an empty directory python3 -m pip install pulsar-client==$VERSION.0 --force-reinstall C_MODULE_PATH=$(python3 -c 'import _pulsar, os; print(_pulsar.__file__)') git clone git@github.com:apache/pulsar-client-python.git cd pulsar-client-python git checkout v$VERSION.0 # You can skip this step if you already have the `pulsar-site` repository in your local env. # In this case, you only need to modify the `--html-output` parameter in the following command. git clone git@github.com:apache/pulsar-site.git sudo python3 -m pip install pydoctor pydoctor --make-html \ --html-viewsource-base=https://github.com/apache/pulsar-client-python/tree/v$VERSION.0 \ --docformat=numpy --theme=readthedocs \ --intersphinx=https://docs.python.org/3/objects.inv \ --html-output=./pulsar-site/static/api/python/$VERSION.x \ --introspect-c-modules \ $C_MODULE_PATH \ pulsar cd pulsar-site git checkout -b py-docs-$VERSION git add . git commit -m "Generate Python client $VERSION.0 doc" git push origin py-docs-$VERSION
Then open a PR like: https://github.com/apache/pulsar-site/pull/600
Use your Apache email account (user@apache.org) to send an email like:
To: dev@pulsar.apache.org, users@pulsar.apache.org, announce@apache.org Subject: [ANNOUNCE] Apache Pulsar Client Python X.Y.Z released The Apache Pulsar team is proud to announce Apache Pulsar Client Python version X.Y.Z. 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. You can download the source code and the Python wheels in: https://archive.apache.org/dist/pulsar/pulsar-client-python-X.Y.Z/ The Python wheels were uploaded to PyPI as well so that they can be installed by `pip install pulsar-client==X.Y.Z`. Release Notes are at: https://pulsar.apache.org/release-notes/versioned/client-python-X.Y.Z/ 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 announce@apache.org 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.