Release Changelog

This guide explains how to generate a changelog between two Git references (tags or commits) using the generate-changelog.sh script in the Cloudberry repo.

Prerequisites

• A local clone of the Cloudberry Git repository.
• jq installed (required by the script).
• A GitHub Personal Access Token exported as GITHUB_TOKEN.

GitHub Token Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Generate a new token with:

• public_repo scope for public repositories, or
• repo scope for private repositories.

3. Export it in your shell:

export GITHUB_TOKEN=your_token_here

Usage

./devops/release/generate-changelog.sh <from_ref> <to_ref> [repo_owner/repo_name]

• <from_ref>: starting Git ref (tag or commit SHA).
• <to_ref>: ending Git ref (tag or commit SHA).
• [repo_owner/repo_name]: optional, defaults to apache/cloudberry.

Examples

# Between two commit SHAs
./devops/release/generate-changelog.sh 1a40e1f 8178d4f

# Between two tags
./devops/release/generate-changelog.sh v1.0.0 v1.1.0

# Explicit repository
./devops/release/generate-changelog.sh v1.0.0 v1.1.0 apache/cloudberry

What the Script Does

• Counts commits between <from_ref> and <to_ref>.
• For each commit, it queries GitHub to find the associated PR.
• Produces a Markdown list with:
  • commit link
  • subject
  • author
  • PR link (if found)

Sample Output

* [`abc1234`](https://github.com/apache/cloudberry/commit/abc1234...) - Fix planner regression (Alice) [#567](https://github.com/apache/cloudberry/pull/567)
* [`def5678`](https://github.com/apache/cloudberry/commit/def5678...) - Improve docs build (Bob)

Where to Publish the Changelog

After generating the changelog, we publish it to the Cloudberry website repository:

• Target repo: apache/cloudberry-site
• Target path: src/pages/releases

This is the canonical location for release notes on the project website.

Notes

• GITHUB_TOKEN is required; the script will exit if it is not set.
• jq must be installed; the script will exit if it is missing.
• The script prints Changelog generation completed! when done.

Troubleshooting

• If you see: Error: GITHUB_TOKEN environment variable is required

  Ensure you’ve exported the token in your shell.

• If you see: Error: jq is required but not installed

  Install jq using your system’s package manager (e.g., brew install jq, apt install jq, etc.).