Skip to content

Release Runbook

Jump to bottom
Dianjin Wang edited this page Jul 16, 2026 · 7 revisions

Note

Draft, still WIP

Prepare GPG KEY (Optional, only for the first time setup)

Please follow this the page GPG Key Setup to create your GPG key and upload to the Apache. Each release manager only creates a GPG KEY for the first time, which can be reused for subsequent releases.

Starting discussion about the new release

Start a discussion about the new release in the dev mailing list.

  • Receiver: dev@cloudberry.apache.org
  • Subject:[DISCUSS] Release Apache Cloudberry x.x.0
  • Body:
Hello, Apache Cloudberry Community,

This is a call for a discussion to release Apache Cloudberry version x.x.0. I would like to take the Release manager role for this release.

Please leave your comments here about this release plan. We will bump the version in repo and start the release process after the discussion.

Thanks,

XXX

If the discussion goes positive, you will need to prepare the release artifacts.

Creating a Release Candidate

Align the release branch commit and version info

  • You must make sure all the commits that wanted to be shipped have been cherry-picked to the release branch and passed all the CI tests.
  • You must make sure the version infos are correct:

Creating a tag

If you want to ship the new release with other components, like cloudberry-pxf, cloudberry-backup, or cloudberry-go-libs, besides the cloudberry core, you need to create the RC tags for each of them.

We take the example of creating an RC tag for the cloudberry core.

# Clone the source using the SSH
git clone git@github.com:apache/cloudberry.git

# Check out the target release branch
git checkout REL_2_STABLE

# Create the tag with the latest commit SHA
git tag -a x.x.0-rc1 2ffc7e60dd4xxxxx -m "Apache Cloudberry (Incubating) x.x.0-incubating-rc1 Release Candidate"

# verify the tag info
git log -n 1
git cat-file -p x.x.0-rc1
git describe

# Push to the repo
git push origin x.x.0-rc1

Generate the artifacts

We have a release script for cloudberry core, cloudberry-pxf and cloudberry-backup.

Before going ahead, you can copy the latest cloudberry-release.sh, cloudberry-pxf-release.sh, and cloudberry-backup-release.sh to a new blank directory.

Then, you can run the release scripts to generate the artifacts:

  • Cloudberry core:
./cloudberry-release.sh --stage \
  --tag x.x.0-incubating-rc1 \
  --repo ~/cloudberry \
  --gpg-user your@apache.org
  • cloudberry-pxf:
./cloudberry-pxf-release.sh --stage \
  --tag x.x.0-incubating-rc1 \
  --repo ~/cloudberry-pxf \
  --gpg-user your@apache.org
  • cloudberry-backup:
./cloudberry-backup-release.sh --stage \
  --tag 2.0.0-incubating-rc1 \
  --repo ~/cloudberry-backup \
  --gpg-user your@apache.org

For more details, you can read Release Staging Guide.

Verify on your local machine

It's recommended you build the cloudberry core, cloudberry-backup and cloudberry-pxf on your local machine to see if all the components can be builded from source on different OSs (Rocky 8/9/10, Ubuntu 22.04/24.04, etc.)

Upload to the dist/dev/incubator/cloudberry

As we described in the GPG Key setup, there are two folders for our release. One is dev folder for the release candidates (https://dist.apache.org/repos/dist/dev/incubator/cloudberry), the other release folder is for the approved release (https://dist.apache.org/repos/dist/release/incubator/cloudberry).

You can create a new release candidate directory for the new release RC:

svn co https://dist.apache.org/repos/dist/dev/incubator/cloudberry cloudberry-dev
cd cloudberry-dev
mkdir -p x.x.0-incubating-rc1

Then move all the artifacts and their signature and checksum files to the new directory, and upload to the Apache SVN site.

svn status # check the file status
svn add x.x.x # add the new files
svn commit -m "Adding the Apache Cloudberry x.x.0-rc1" # Upload to the ASF SVN site

Start a VOTE

  • Subject: [VOTE] Release Apache Cloudberry (Incubating) x.x.0-rc1
  • Body:
Hi all,

I would like to call a VOTE to release Apache Cloudberry (Incubating) x.x.0-rc1.

## Release Candidate Artifacts

This vote covers the source release artifacts for Apache Cloudberry (Incubating) x.x.0-rc1, including the main Cloudberry project and the two components cloudberry-backup and cloudberry-pxf.

Staged release artifacts:
https://dist.apache.org/repos/dist/dev/incubator/cloudberry/x.x.0-incubating-rc1/

Git tag & commit for the release:
- cloudberry
 https://github.com/apache/cloudberry/tree/x.x.0-incubating-rc1
 https://github.com/apache/cloudberry/commit/bdf90c5xxxxxxx

- cloudberry-backup
 https://github.com/apache/cloudberry-backup/tree/x.x.0-incubating-rc1
 https://github.com/apache/cloudberry-backup/commit/c909fbexxxxxx

- cloudberry-pxf
 https://github.com/apache/cloudberry-pxf/tree/x.x.0-incubating-rc1
 https://github.com/apache/cloudberry-pxf/commit/59dceddxxxxxxxxxx

KEYS file:
https://downloads.apache.org/incubator/cloudberry/KEYS

GPG signature key: 9A36AA272348A20XXXXXXXXXX

The GPG user ID(s): XXX XXXX <xxxxx@apache.org>

## How to Vote

Please review the release and cast your vote below. If you are a PPMC member, please indicate whether your vote is binding. Also, that would be better to list the items you checked in your reply - it shows what you vote for.

[ ] +1 Approve the release
[ ]  0 No opinion
[ ] -1 Disapprove (please explain why)

The vote is open for at least 72 hours and will close no earlier than March 8, 2026 at 08:00 UTC.

## Checklist for reference:

[ ] Download links are valid and accessible.
[ ] GPG signature is valid for the release artifact using the KEYS file.
[ ] SHA512 checksums are correct and verified.
[ ] Source release artifact filename includes "incubating".
[ ] LICENSE, NOTICE, and DISCLAIMER files exist and are accurate.
[ ] No unexpected binary files in the source release.
[ ] All source files have appropriate ASF headers (excluding generated files and legacy files).
[ ] Build completes successfully from source with clear instructions.

More detail checklist, please refer to: https://github.com/apache/cloudberry/wiki/Source-Release-Checklist

Build/Install guides (for reference):
- cloudberry: https://cloudberry.apache.org/docs/deployment/quick-build#for-apache-cloudberry-XXX
- cloudberry-pxf: https://github.com/apache/cloudberry-pxf/blob/x.x.0-incubating-rc1/README.md
- cloudberry-backup: https://github.com/apache/cloudberry-backup/blob/x.x.0-incubating-rc1/README.md

## GPG Signature and SHA512 checksums Verification Instructions

Please refer to our step-by-step guide: https://cloudberry.apache.org/releases/#verifying-releases

## About Convenience Binaries

After this source release vote passes and the release is published, we plan to provide optional convenience binary packages via GitHub Releases for easier testing. These binaries are not part of this vote and are not ASF release artifacts.

Thanks for reviewing and voting!

Best,
XXXX

Send to Apache Incubator Mailing list

RC1

  • Subject: [VOTE] Release Apache Cloudberry (Incubating) x.x.0-rc1
  • Body:
Hello Incubator Community,

This is a call for vote to release Apache Cloudberry (Incubating) x.x.0-rc1.

The Apache Cloudberry (Incubating) community has voted to release version x.x.0-rc1. We now kindly request the Incubator PMC's approval.


Community vote thread:
https://lists.apache.org/thread/xxxxxxx

Vote result thread:
https://lists.apache.org/thread/xxxxxxx


Release candidate artifacts:
https://dist.apache.org/repos/dist/dev/incubator/cloudberry/x.x.x-incubating-rc1/

Git tag & commit for the release:
- https://github.com/apache/cloudberry/tree/x.x.0-incubating-rc1 (bdf90c5)
- https://github.com/apache/cloudberry-backup/tree/x.x.0-incubating-rc1 (c909fbe)
- https://github.com/apache/cloudberry-pxf/tree/x.x.0-incubating-rc1 (59dcedd)

The artifacts have been signed with key [9A36AA272348A207E19xxxxxxxxx], corresponding to xxxx@apache.org, available here: https://downloads.apache.org/incubator/cloudberry/KEYS

Please vote on releasing this candidate as Apache Cloudberry (Incubating) x.x.0.

[ ] +1 Approve the release
[ ] 0 No opinion
[ ] -1 Disapprove (please explain why)

This vote will be open for at least 72 hours.

Checklist for reference:

[ ] Download links are valid and accessible.
[ ] GPG signature is valid for the release artifact using the KEYS file.
[ ] SHA512 checksums are correct and verified.
[ ] Source release artifact filename includes "incubating".
[ ] LICENSE, NOTICE, and DISCLAIMER files exist and are accurate.
[ ] No unexpected binary files in the source release.
[ ] All source files have appropriate ASF headers (excluding generated
files and legacy files).
[ ] Build completes successfully from source with clear instructions.

More detailed checklist, please refer to:
https://github.com/apache/cloudberry/wiki/Source-Release-Checklist

Build/Install guides (for reference):
- cloudberry: https://cloudberry.apache.org/docs/deployment/quick-build#for-apache-cloudberry-XX0
- cloudberry-pxf:
https://github.com/apache/cloudberry-pxf/blob/x.x.0-incubating-rc1/README.md
- cloudberry-backup:
https://github.com/apache/cloudberry-backup/blob/x.x.0-incubating-rc1/README.md


To learn more about Apache Cloudberry (incubating) , please see https://cloudberry.apache.org/

Thanks,
XXXX
On behalf of Apache Cloudberry (Incubating) community

RESULT VOTE

general@incubator.apache.org

  • Subject: [RESULT] [VOTE] Release Apache Cloudberry (Incubating) 2.1.0-rc1
  • Body:
Hello Incubator Community,

The vote to release Apache Cloudberry (Incubating) x.x.0-rc1 has passed with XXX +1 binding votes, XXX +1 non-binding, no +0 or -1 votes.

+1 binding:
- XXXX (binding)
- XXXX (binding)
- XXXX (binding)

+1 Non-binding:
- XXXX (non-binding)
- XXXX (non-binding)

Vote thread:
https://lists.apache.org/thread/xxxxxx

Thanks for reviewing and voting for our release candidate.

We will proceed with publishing the approved artifacts and sending out the
announcement soon.

Promote the RC to the final release

Remove the old release

svn del -m "Archiving release 2.0.0" https://dist.apache.org/repos/dist/release/incubator/cloudberry/2.0.0-incubating/

Update the Release Page

Generate the changelog

Update the Release Page

Announce new Release

  • to: annouce@apache.org
  • cc: general@incubator.apache.org, dev@cloudberry.apache.org
  • subject: [ANNOUNCE] Apache Cloudberry (Incubating) x.x.0 released
  • body:
The Apache Cloudberry (Incubating) community is pleased to announce the release of Apache Cloudberry (Incubating) version x.x.0.

Apache Cloudberry (Incubating) is a Massively Parallel Processing (MPP)
database for large-scale data analytics, derived from PostgreSQL and the
last open-source version of Greenplum Database. It is designed to support
both on-premise and cloud deployments, providing a scalable foundation
for data warehousing and advanced analytics.

This release covers the main Cloudberry project and the
two components cloudberry-backup and cloudberry-pxf.

Download and verification:
https://cloudberry.apache.org/releases

Changelog:
https://cloudberry.apache.org/releases/x.x.0-incubating

For documentation, visit:
https://cloudberry.apache.org/docs/

Website: https://cloudberry.apache.org

Resources:
- Repository: https://github.com/apache/cloudberry
- Discussions: https://github.com/apache/cloudberry/discussions
- Issue tracker: https://github.com/apache/cloudberry/issues
- Mailing list: https://lists.apache.org/list.html?dev@cloudberry.apache.org

Thanks to everyone who participated in the development and release!

Apache Cloudberry is an effort undergoing incubation at the Apache
Software Foundation (ASF), sponsored by the Apache Incubator PMC.
Incubation is required of all newly accepted projects until a review by
the Incubator PMC demonstrates that the project has met the ASF’s
requirements for community and process. While incubation status is not
necessarily a reflection of the project’s stability or readiness for
production, it does indicate that the project is working towards
compliance with ASF processes and governance.


XXX XX
On behalf of Apache Cloudberry (Incubating) Team

Follow-ups

Write an announcement blog

You can take the following blog posts as the reference to write your own announcement blog post:

Generate the convenience packages

Note

There are no strong rules requiring you to generate the convenience packages along with the official Release. For Apache release, it only means the source tarball, not that it includes these convenience packages. But it would be better to provide these package behind one or two weeks after the official release.

  1. Convenience package build workflow for Apache Cloudberry

Now we have one Apache Cloudberry Convenience Package Build workflow to help the release manager to generate the convenience packages automatically.

You can click the Run workflow button, then input the following files:

  • Release version, e.g. 2.1.0-incubating
  • Release source tarball URL, e.g. https://downloads.apache.org/incubator/cloudberry/2.1.0-incubating/apache-cloudberry-2.1.0-incubating-src.tar.gz
  • GPG signature URL for the source tarball, e.g. https://downloads.apache.org/incubator/cloudberry/2.1.0-incubating/apache-cloudberry-2.1.0-incubating-src.tar.gz.asc
  • SHA-512 checksum URL for the source tarball, e.g. https://downloads.apache.org/incubator/cloudberry/2.1.0-incubating/apache-cloudberry-2.1.0-incubating-src.tar.gz.sha512

After inputting these data, you can click to run. This workflow supports generating the DEB/RPM packages under Rocky8/9/10 and Ubuntu 22.04/24.04 with their checksum files. But please note, after downloading these DEB/RPM packages, you still need to sign these files with your own GPG key:

gpg --armor --detach-sign --local-user xxx@apache.org apache-cloudberry-incubating-x.x.0-1.elN.x86_64.rpm

Then you can verify the GPG signature:

gpg --verify apache-cloudberry-incubating-x.x.0-1.elN.x86_64.rpm.asc apache-cloudberry-incubating-x.x.0-1.elN.x86_64.rpm
  1. For other components, including cloudberry-backup and cloudberry-pxf, you need to generate the convenience packages manually for now. You can take this guide as a reference.

You can use the same way to sign these packages with your own GPG keys described in step 1. For generating the SHA512 checksum, you can use the following command:

sha512sum apache-cloudberry-pxf-x.x.0-1.el8.x86_64.rpm apache-cloudberry-pxf-x.x.0-1.el8.x86_64.rpm.sha512

Then verify the checksum:

sha512sum -c apache-cloudberry-pxf-x.x.0-incubating-src.tar.gz.sha512
  1. Run the basic verification.

It would be better to install these convenience binaries on a pure Rocky 8/9/10 or Ubuntu 22.04/24.04 platform and run the basic demo or basic command.

  • For Cloudberry core: follow these steps to install RPM/DEB and start a single-node demo cluster.
  • For cloudberry-backup: follow these steps to install cloudberry-backup package, and you can run the following basic commands under the Cloudberry demo environment:
gpbackup --dbname postgres

gprestore --dbname postgres --timestamp YYYYMMDDHHMMSS # YYYYMMDDHHMMSS is the timestamp showed in the gpbackup command
  • For cloudberry-pxf：
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk

export PXF_HOME=/usr/local/cloudberry-pxf

export PXF_BASE={HOME}/pxf-base 
export PATH=/usr/local/cloudberry-pxf/bin:PATH

pxf start
pxf restart
pxf stop
  1. Upload the package files and their signature and checksum files (RPM/DEB + .asc + .sha512) to the GitHub Release pages. Also, please remember to update the information on the download page on the Cloudberry site.

Clone this wiki locally