ParadeDB Release Process

We use a single branch, main, for our development. Features are built on separate branches and merged into main via pull requests.

ParadeDB uses a fragment-based workflow for release artifacts:

  • PRs that introduce user-facing changes add a changelog fragment to docs/changelog/unreleased/<PR>.<category>.mdx.
  • PRs that modify extension DDL/schema add a SQL migration fragment to pg_search/sql/unreleased/<PR>.<description>.sql.

At release time, the Publish GitHub Release workflow automatically assembles these fragments into the versioned SQL upgrade script and changelog page.

Release Types

Type Description
Minor Triggered from the main branch. Publishes x.y.0 and creates stable branch x.y.x.
Patch Triggered from a stable branch (e.g., 0.25.x). Publishes x.y.z and syncs artifacts to main.
Beta (RC) Marked with beta: true. Can be triggered from any branch/commit. Produces a tag like vX.Y.Z-rc.N without modifying the branch.

Note: Minor and patch releases publish Docker images for all supported PostgreSQL major versions and prebuilt extension binaries for all supported platforms. Beta releases publish only the PostgreSQL 18 Docker image and the Debian 13 packages required to build it; the remaining prebuilt extension binaries are skipped.

Workflow Inputs

Input Type Default Description
version string "" Target release version in semver format (e.g., 1.2.3 or 1.2.3-rc.1 for beta releases).
beta boolean false If true, creates a beta release (e.g., vX.Y.Z-rc.N) and marks it as a pre-release in GitHub.

Triggering a Release

Minor Releases

To publish a minor release from main:

  1. Go to Actions → Publish GitHub Release
  2. Click Run workflow, select main as the release branch, and provide the target version (e.g. 0.26.0).
  3. Click Run workflow to start the job.
  4. The workflow will automatically:
    • Run scripts/release.sh all to assemble pg_search/sql/unreleased/*.sql into pg_search--<prev>--<version>.sql, assemble docs/changelog/unreleased/*.mdx into docs/changelog/<version>.mdx, register the release in docs/docs.json, and remove the consumed fragments.
    • Bump workspace.package.version in Cargo.toml and synchronize Cargo.lock.
    • Commit and push the release commit to main.
    • Create the Git tag v<version>, triggering downstream packaging and publishing workflows.
    • Create the stable branch x.y.x pointing at the release commit.
    • Bump main to the next development version (e.g., 0.27.0).

Beta (RC) Releases

To publish a beta release from any branch or commit:

  1. Go to Actions → Publish GitHub Release
  2. Click Run workflow, select the desired branch or commit, provide the version (e.g. 0.26.0-rc.0 or 0.25.6-rc.1), and check beta: true.
  3. Click Run workflow to start the job.
  4. The workflow will automatically:
    • Assemble pg_search/sql/unreleased/*.sql into pg_search--<prev>--<version>.sql while preserving the unreleased fragments.
    • Skip changelog and docs generation.
    • Create and push the Git tag v<version> pointing directly to the release commit, without pushing commits to the release branch.

Patch Releases

Fixes intended for a stable release are labeled with cherry-pick/<branch> (e.g. cherry-pick/0.25.x) on main and automatically backported via .github/workflows/cherry-pick.yml upon merge into the stable branch.

To publish a patch release from a stable branch:

  1. Go to Actions → Publish GitHub Release.
  2. Click Run workflow, select the stable branch (e.g. 0.25.x) as the release branch, and provide the patch version (e.g. 0.25.5).
  3. The workflow will automatically:
    • Assemble the unreleased fragments present on the stable branch into pg_search--<prev>--<version>.sql and docs/changelog/<version>.mdx.
    • Bump Cargo.toml and synchronize Cargo.lock on the stable branch.
    • Commit, tag v<version>, and publish the GitHub release.
    • Sync to main: Check out main, copy the assembled SQL script and changelog page, update docs/docs.json, delete the consumed fragments from main, and push the sync commit to main.

Post-Release Steps

  1. Verify that the GitHub release and tag were created correctly and that all downstream packaging jobs completed successfully.
  2. Release paradedb/paradedb-enterprise by following the instructions in the repository’s RELEASE.md file.

That’s it! Go for a walk, you deserve it.