GreptimeDB Release Notes

GreptimeDB Release Note / Changelog

Generate the changelog for a GreptimeDB release. Tooling: git cliff (config: cliff.toml in the greptimedb repo) and gh. Run inside the greptimedb checkout.

Prerequisites: git cliff, gh (check gh auth status), and Python (the subtract-PRs / rebuild-contributors step in §3–§4 is scripted). This skill writes <remote> for the git remote pointing at GreptimeTeam/greptimedb (often upstream, sometimes origin); resolve it with git remote -v | grep -i 'GreptimeTeam/greptimedb' | awk '{print $1}' | head -1.

1. GitHub token (never print it)

git cliff enriches commits with PR titles/authors via the GitHub API; for hundreds of commits you need a token or you hit rate limits. Pass it inline and never read or echo the token:

GITHUB_TOKEN=$(gh auth token) git cliff ...

Alternatively the user sources an env file that exports GITHUB_TOKEN (don't read it). Without a token it still runs, but may be rate-limited / incomplete.

2. Determine the previous version (skip nightlies)

From gh release list --repo GreptimeTeam/greptimedb, ignore *-nightly-*, -rc.*, -beta.*, and build-suffixed tags; focus on formal vX.Y.Z.

• Patch vX.Y.Z (Z>0): previous = vX.Y.(Z-1).
• New minor vX.Y.0: previous = the latest vX.(Y-1).* (for v1.0.0, the biggest 0.x). Double-check with the user.

3. Pick the range and generate

Key topology fact: a minor tag (e.g. v1.0.0) is an ancestor of main; patch tags (v1.0.1, v1.0.2) live on the release/v1.0 branch and are NOT ancestors of main (they are cherry-picks with different SHAs). Verify with git merge-base --is-ancestor <tag> <remote>/main.

New minor (X.Y.0, cut from main)

Note the two different tags here: the git cliff base is the previous minor .0 tag (e.g. v1.0.0, an ancestor of main) — not the "previous version" from §2 (the latest patch, e.g. v1.0.2), which is only used below to decide which patch PRs to subtract.

Base = the previous minor tag (e.g. v1.0.0); tip = the release commit (= release/vX.Y tip, usually <remote>/main):

GITHUB_TOKEN=$(gh auth token) git cliff <prev-minor-tag>..<release-commit> --tag vX.Y.0 \
  -o /path/CHANGELOG-vX.Y.0.md

cliff.toml's ignore_tags folds in-range nightly tags into the single section.

Then subtract PRs already shipped in the intermediate patch releases (vX.(Y-1).1, .2, …) — their main-branch commits are inside the range and would duplicate, and the audience cares about what's new vs the latest patch. Collect the PR set from the patch release bodies and remove matching lines:

gh release view vX.(Y-1).Z --repo GreptimeTeam/greptimedb | grep -oE 'pull/[0-9]+'

Remove every changelog bullet whose #NNNN is in that combined set (a small Python script is the reliable way — match pull/<n>) on lines starting with *).

Patch (X.Y.Z, Z>0, cherry-picks on the release branch)

The previous patch tag is an ancestor of the release branch, so a plain range works when the cherry-picks land as individual commits:

GITHUB_TOKEN=$(gh auth token) git cliff <prev-patch-tag>..<release-branch-tip> --tag vX.Y.Z -o ...

No extra subtraction (the branch only contains the new cherry-picks).

Common case — squashed pick commit. Patch branches are often a single squashed commit like chore: pick fixes and bump version to vX.Y.Z (#NNNN), so the plain range above yields just that one bullet. First find the picked PRs: read the squash commit message (git log -1 --format=%B <release-branch-tip>) — each * fix: ... (#NN) line is a picked PR. Then pick one of two ways to build the changelog (a patch is usually only a few PRs — ask the user which they prefer):

• (a) Generate on main and filter — lets git cliff produce correctly formatted bullets (titles, authors, categories):
  1. Locate and order the picked PRs' commits on main chronologically:

     git log --oneline <remote>/main --grep='#NN1' --grep='#NN2' --reverse

     The first line is the oldest pick, and the last line is the newest pick.
  2. Run cliff over a main range covering all of them (base = parent of the oldest picked commit, tip = the newest), then keep only the picked #NN bullets:

     GITHUB_TOKEN=$(gh auth token) git cliff <oldest-pick>~1..<newest-pick> --tag vX.Y.Z -o /tmp/raw.md

     The raw output includes unrelated PRs in the main range that were not picked — drop them, then rebuild contributors (§4).
• (b) Hand-write the bullets — a fine fallback for a small patch (and when the API/network is flaky). For each picked PR fetch its title + author (gh api repos/GreptimeTeam/greptimedb/pulls/<n>) and write the * <title> by [@user] in [#NN](...) lines plus the contributor list yourself.

If the branch history is otherwise messy, the same "identify the picked PRs and keep only those" rule applies.

Flaky-network note for (a): git cliff fetches the repo's full commit history from the GitHub API for author enrichment (paginates back thousands of commits, even for a tiny range). On a flaky connection it can time out mid-pagination; it caches pages, so just re-run until it completes — each retry resumes from the cache. If it keeps failing, fall back to (b).