Release Staging Guide

This document describes how to use the cloudberry-release.sh script to prepare an Apache Cloudberry (Incubating) release candidate.

It is intended for Release Managers and PPMC members responsible for creating source artifacts.

1. Overview

The cloudberry-release.sh script automates the following tasks:

• Validates version consistency across:
  • configure.ac
  • configure
  • gpMgmt/bin/gppylib/gpversion.py
  • pom.xml
• Validates Git repository state and upstream remote
• Checks required tools (sha512sum, tar/gtar, gpg, xmllint)
• Creates and validates Git release tags
• Ensures Git submodules are initialized
• Builds source tarballs including submodules
• Generates:
  • SHA-512 checksum (.sha512)
  • GPG signature (.asc)
• Verifies artifact integrity and authenticity

This script aims to ensure reproducible and policy-compliant Apache releases.

2. Prerequisites

2.1 Required Tools

Tool	Purpose
git	Source control
sha512sum	SHA-512 checksum generation
tar / gtar	Source packaging
gpg	Artifact signing
xmllint	Parsing pom.xml

• macOS:

brew install coreutils gnu-tar gnupg

• Linux (Debian/Ubuntu):

sudo apt install coreutils tar gnupg libxml2-utils

2.2 Repository Requirements

• Must be run from the root of a Cloudberry Git clone, or specify --repo <path>

• Working tree must be clean (no uncommitted changes)

• Official releases must use upstream remote:

  [email protected]:apache/cloudberry.git
  

  Use --skip-remote-check only for testing or forks.

2.3 GPG Setup

You must have a valid Apache GPG key imported:

gpg --list-keys [email protected]

If missing, generate or import your key before proceeding.

3. Tag and Version Policy

3.1 Tag Format

The script enforces semantic versioning with an incubator suffix:

<MAJOR>.<MINOR>.<PATCH>-incubating
<MAJOR>.<MINOR>.<PATCH>-incubating-rc<N>

Examples:

• 2.0.0-incubating
• 2.0.0-incubating-rc1

3.2 Version Consistency Rules

The following files must match the base version (without -rc):

File	Expected Value
configure.ac	Base version
configure	Base version
pom.xml	Base version
gpversion.py	MAIN_VERSION = [MAJOR,99]

If any mismatch exists, the script will abort.

4. Usage

4.1 Stage a Release Candidate

./cloudberry-release.sh --stage \
  --tag 2.0.0-incubating-rc1 \
  --gpg-user [email protected]

4.2 Reuse an Existing Tag (Only if Tag == HEAD)

./cloudberry-release.sh --stage \
  --tag 2.0.0-incubating-rc1 \
  --force-tag-reuse \
  --gpg-user [email protected]

4.3 Skip Signing (Testing Only)

./cloudberry-release.sh --stage \
  --tag 2.0.0-incubating-rc1 \
  --skip-signing

⚠️ Do not use this for official Apache releases.

4.4 Use a Local Repo Path

./cloudberry-release.sh --stage \
  --tag 2.0.0-incubating-rc1 \
  --repo ~/cloudberry \
  --gpg-user [email protected]

5. What the Script Does

Step 1: Platform & Tool Detection

Ensures consistent cross-platform behavior.

Step 2: Version Validation

Ensures all version files are aligned with the release tag.

Step 3: Git Tag Validation

• Prevents tag mutation
• Allows reuse only when explicitly forced and matches HEAD

Step 4: Submodule Validation

Ensures all submodules are initialized:

git submodule update --init --recursive

Step 5: Source Tarball Generation

Recursively archives repository and submodules

• Excludes macOS metadata files (._*, .DS_Store, __MACOSX) when under macOS
• Adds BUILD_NUMBER file for traceability

Step 6: Signing and Checksums

• Generates .sha512
• Generates .asc signature
• Verifies integrity and authenticity

Artifacts are moved into an artifacts/ directory.

6. Output Artifacts

Typical outputs:

apache-cloudberry-2.0.0-incubating-rc1-src.tar.gz
apache-cloudberry-2.0.0-incubating-rc1-src.tar.gz.sha512
apache-cloudberry-2.0.0-incubating-rc1-src.tar.gz.asc

7. Recommended Release Manager Workflow

• Ensure versions are updated in all required files
• Ensure working tree is clean
• Run cloudberry-release.sh
• Upload artifacts to Apache dist staging (SVN)
• Start community vote on [email protected]
• After vote passes, publish to Apache dist release area

8. Notes and Best Practices

• Tags must be immutable
• Always use -rc<N> for voting candidates
• Never upload unsigned artifacts to Apache dist
• Keep release process reproducible and scripted
• Use mailing list voting per ASF policy

9. Troubleshooting

• Missing Tools

  The script prints platform-specific installation guidance.

• Version Mismatch

  Update version in all files and rerun autoconf:

  autoconf
  

Please use autoconf 2.69 on Rocky Linux 9 to generate the new configure file.

• GPG Key Not Found

  Import or generate your Apache GPG key.