Skip to content

Release process

Jump to bottom
Zixuan Liu edited this page Dec 9, 2024 · 18 revisions

WORK-IN-PROGRESS

This page contains instructions for Pulsar committers on how to perform a release for Pulsar Adapters

Please refer to the wiki on the main Pulsar repo in order to setup your environment https://github.com/apache/pulsar/wiki

If you haven't already done it, create and publish the GPG key to sign the release artifacts.

Before you start the next release steps, make sure you have installed the JDK17 and maven 3.6.1.

Ensure the Pulsar has been released

Usually a release from this repo matches a release of the main repo, so for instance the 2.11.0 release will be based on Pulsar 2.11.0. This means that Pulsar 2.11.0 must be released before cutting the 2.11.0 release from this repo.

Release workflow

The steps for releasing are as follows:

  • Create release branch
  • Update project version and tag
  • Build and inspect the artifacts
  • Inspect the artifacts
  • Stage artifacts in maven
  • Move master branch to next version
  • Write release notes
  • Run the vote
  • Promote the release
  • Update release notes
  • Update the site
  • Announce the release
  • Remove old releases

The following are details for each step.

Create the release branch

We are going to create a branch from master to branch-v2.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 patch releases like 2.3.1. For patch and minor release, goto next step.

Eg: When creating v2.3.0 release, the branch branch-2.3 will be created; but for v2.3.1, we keep using the old branch-2.3.

In these instructions, I'm referring to a fictitious release 2.X.0. Change the release version in the examples accordingly with the real version.

It is recommended to create a fresh clone of the repository to avoid any local files to interfere in the process:

git clone [email protected]:apache/pulsar-adapters.git
cd pulsar
git checkout -b branch-2.X origin/master
git push origin branch-2.X

Ensure that the build is passing

Probably you have to build the integration tests artifacts from Pulsar repo

git clone https://github.com/apache/pulsar
git checkout v2.X.0
cd pulsar
mvn -B -ntp -f tests/pom.xml -pl org.apache.pulsar.tests:tests-parent,org.apache.pulsar.tests:integration install -DskipTests
docker pull apachepulsar/pulsar-all:2.X.0
docker pull apachepulsar/pulsar:2.X.0
docker tag apachepulsar/pulsar-all:2.X.0 apachepulsar/pulsar-all:latest
docker tag apachepulsar/pulsar:2.X.0 apachepulsar/pulsar:latest
mvn -B -ntp -f tests/docker-images/pom.xml install -pl org.apache.pulsar.tests:latest-version-image -am -Pdocker,-main -DskipTests

Run the build from the sources

mvn clean install -DskipTests

Update project version and tag

During the release process, we 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.

mvn release:prepare -Darguments="-DskipTests" -DautoVersionSubmodules -Papache-release

Answer to the questions. The tag name should be like 'v2.11.0-candidate-1'

Stage artifacts

mvn release:perform -DreleaseProfiles=apache-release -Darguments="-DskipTests"  -Papache-release

Stage the artifacts

VERSION=2.X.0
RCVERSION=$VERSION-candidate-1
PULSAR_ADAPTERS_HOME="path/to/pulsar-adapters"

svn mkdir -m "Add directory for pulsar-adapters $RCVERSION release" https://dist.apache.org/repos/dist/dev/pulsar/pulsar-adapters-$RCVERSION
svn co https://dist.apache.org/repos/dist/dev/pulsar/pulsar-adapters-$RCVERSION

cd pulsar-adapters-$RCVERSION
cp $PULSAR_ADAPTERS_HOME/target/apache-pulsar-adapters-$VERSION-src.tar.gz* .
sha512sum apache-pulsar-adapters-$VERSION-src.tar.gz > apache-pulsar-adapters-$VERSION-src.tar.gz.sha512sum
gpg --armor --output apache-pulsar-adapters-$VERSION-src.tar.gz.asc --detach-sig apache-pulsar-adapters-$VERSION-src.tar.gz

svn add *
svn ci -m "Staging artifacts and signature for Pulsar Adapter $RCVERSION"

Stage artifacts in maven

Login to ASF Nexus repository at https://repository.apache.org

Click on "Staging Repositories" on the left sidebar and then select the current Pulsar staging repo. This should be called something like orgapachepulsar-XYZ.

Use the "Close" button to close the repository. This operation will take few minutes. Once complete click "Refresh" and now a link to the staging repository should be available, something like https://repository.apache.org/content/repositories/orgapachepulsar-XYZ

Write release notes

Check the milestone in Github associated with the release. https://github.com/apache/pulsar-adapters/milestones?closed=1

In the release item, add the list of most important changes that happened in the release and a link to the associated milestone, with the complete list of all the changes.

8. Run the vote

Send an email on the Pulsar Dev mailing list:

To: [email protected]
Subject: [VOTE] Apache Pulsar Adapters Release 2.X.0 Candidate 1

This is the first release candidate for Apache Pulsar Adapters, version 2.X.0.

It fixes the following issues:
https://github.com/apache/pulsar-adapters/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-adapters-2.X.0-candidate-1/

SHA-512 checksums:

6f1f34fc454fdaa9b5065d0dce96d468d8b5081cff333564cb88dca7e9c9aba828bb7469bb8c3aa4d23fe653d1a03285418d9ba36d5617a39a783e0433d01dba  apache-pulsar-2.X.0-src.tar.gz

Maven staging repo:
https://repository.apache.org/content/repositories/orgapachepulsar-1091/

The tag to be voted upon:
v2.X.0-candidate-1 (581fee3b68caaf74122e7051e9741494b57fcbd7)
https://github.com/apache/pulsar-adapters/releases/tag/v2.X.0-candidate-1

Pulsar's KEYS file containing PGP keys we use to sign the release:
https://dist.apache.org/repos/dist/dev/pulsar/KEYS

Please download the source package, and follow the README to build the Pulsar Adapters code

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, we can then proceed to next step.

Promote the release

Create the final git tag:

git tag -u $USER@apache.org v2.X.0 -m 'Release v2.X.0'
git push origin v2.X.0

Promote 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 2.X.0" https://dist.apache.org/repos/dist/dev/pulsar/pulsar-adapters-2.X.0-candidate-1 \
         https://dist.apache.org/repos/dist/release/pulsar/pulsar-adapters-2.X.0

Promote the Maven staging repository for release. Login to https://repository.apache.org and select the staging repository associated with the RC candidate that was approved. The naming will be like orgapachepulsar-XYZ. Select the repository and click on "Release". Artifacts will now be made available on Maven central.

Update Pulsar WebSite

Send a PR in order to add the release to the website Download page.

Announce the release

Once the release artifacts are available in the Apache Mirrors and the website is updated, we need to announce the release.

Send an email on these lines:

To: [email protected], [email protected], [email protected]
Subject: [ANNOUNCE] Apache Pulsar Adapters 2.X.0 released

The Apache Pulsar team is proud to announce Apache Pulsar Adapters version 2.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.

Pulsar Adapters is a secondary package that includes many integration with third party projects
like Apache Log4j, Apache Kafka and Apache Storm.
 
For Pulsar release details and downloads, visit:

https://pulsar.apache.org/download

Release Notes are at:
http://pulsar.apache.org/release-notes

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.

Remove old releases

Remove the old releases (if any). We only need the latest release there, older releases are available through the Apache archive:

# Get the list of releases
svn ls https://dist.apache.org/repos/dist/release/pulsar

# Delete each release (except for the last one)
svn rm https://dist.apache.org/repos/dist/release/pulsar/pulsar-adapters-2.Y.0
Clone this wiki locally