/changelog

name: changelog
description: Update per-package CHANGELOG.md files for a Ratel release. Drafts entries with git-cliff (scoped per package), lets you curate, then writes the CHANGELOGs. Handles both RC entries and GA-graduation collapse (merging X.Y.Z-rc.* sections into a single X.Y.Z section). Invoke before tagging a release.

/changelog

Updates a release unit's `CHANGELOG.md` in preparation for tagging it. Ratel releases **per unit** (ADR-0008): each unit ships on its own tag (`<prefix>-v*`) at its own version. For workflow-wired units, `.github/workflows/release.yml` rejects a tag whose unit CHANGELOG doesn't contain the version being released. `vercel-ai-sdk` is temporarily published manually via `scripts/publish-rc.sh`; still run this skill before its tag even though the workflow gate does not cover it yet.

Run it **once per unit** you're releasing.

Release units it touches

The units and their manifests/CHANGELOGs live in one registry — `scripts/release-units.mjs` — which every release tool reads. Run `node scripts/release-units.mjs --list` for the authoritative set; the current eight units are:

| Unit | Registry | CHANGELOG path | |---|---|---| | `core` | `ratel-ai-core` (crates.io) | `src/core/CHANGELOG.md` | | `sdk-ts` | `@ratel-ai/sdk` (npm) | `src/sdk/ts/CHANGELOG.md` | | `sdk-py` | `ratel-ai` (PyPI) | `src/sdk/python/CHANGELOG.md` | | `telemetry-core` | `ratel-ai-telemetry` (crates.io) | `src/telemetry/core/CHANGELOG.md` | | `telemetry-ts` | `@ratel-ai/telemetry` (npm) | `src/telemetry/ts/CHANGELOG.md` | | `telemetry-py` | `ratel-ai-telemetry` (PyPI) | `src/telemetry/python/CHANGELOG.md` | | `vercel-ai-sdk` | `@ratel-ai/vercel-ai-sdk` (npm) | `src/adapters/ts-vercel-ai-sdk/CHANGELOG.md` | | `mastra` | `@ratel-ai/mastra` (npm) | `src/adapters/ts-mastra/CHANGELOG.md` |

`@ratel-ai/mcp-server` lives in [ratel-ai/ratel-mcp](https://github.com/ratel-ai/ratel-mcp) and maintains its own CHANGELOG there.

Procedure

1. Pick the unit and read its version

If the user hasn't named the unit, run `node scripts/releasable.mjs` — it lists which units have commits since their last release tag. Pick the unit `$UNIT` being released.

Read its canonical version:

node scripts/release-units.mjs --version "$UNIT"   # -> $TARGET

If the user supplies a different version explicitly, prefer that and warn them the working tree disagrees.

2. Determine the diff range

The range is from the unit's **own** last release tag to `HEAD`:

prefix=$(node scripts/release-units.mjs --tag-prefix "$UNIT")
FROM=$(git describe --tags --match "${prefix}*" --abbrev=0 2>/dev/null || true)

If `$FROM` is empty the unit has never shipped; the whole history is in range.

3. Generate the draft

bash .claude/skills/changelog/draft.sh --unit "$UNIT"

It emits a single `### <package-name>` block for the unit, containing either Keep-a-Changelog sections (`### Added`, `### Fixed`, `### Changed`) or the sentinel `_No user-facing changes._`. (Omit `--unit` to draft every unit at once.) With no `<from-ref>` argument the script ranges each unit from its own last tag automatically.

If `draft.sh` exits 127, git-cliff is missing. Tell the user how to install it (the script's stderr already does), and stop.

4. Branch on RC vs GA

Inspect `$TARGET`, and edit only **this unit's** CHANGELOG:

• **RC** (`X.Y.Z-rc.N`): prepend a new section above the most recent versioned section:

  ## [X.Y.Z-rc.N] - YYYY-MM-DD

  <draft content for the unit, or the sentinel>

Use today's date in `YYYY-MM-DD` (UTC).

• **GA** (no `-rc` suffix): enter **GA-collapse mode**:

1. Find every `## [X.Y.Z-rc.*]` section already present that matches the same `MAJOR.MINOR.PATCH` as `$TARGET`. 2. Union their bullet entries (per subsection: `### Added`, `### Changed`, `### Fixed`) with the new draft entries from step 3 (commits since the last RC tag). 3. Deduplicate bullets within each subsection (case-insensitive, whitespace-normalised). 4. Drop the `_No user-facing changes._` sentinel if any real entries exist; keep it only if the unioned set is empty. 5. Replace all the matched RC sections with a single `## [X.Y.Z] - YYYY-MM-DD` section containing the merged content. 6. Leave non-matching prior versions (e.g. `## [0.1.4]`) untouched.

5. Curate with the user

Show the unit's CHANGELOG pending changes in the conversation. Ask the user to confirm or edit. Common curation moves:

• Rephrase bullets for user-facing clarity (the draft uses commit subjects verbatim).
• Drop bullets that are not user-visible (internal refactors that slipped past

`cliff.toml`'s skip rules).

• Merge duplicates that survived deduplication.
• Promote / demote between Added / Changed / Fixed if the commit prefix was wrong.

6. Write the file

Once approved, write **only this unit's** CHANGELOG using the Edit tool. **Do not commit.** The release commit is the user's responsibility — they typically include the CHANGELOG alongside the version bump in a single `release: <unit>-vX.Y.Z` commit.

If releasing more than one unit, repeat from step 1 for each.

7. Remind

Tell the user:

• The CHANGELOG is staged in the working tree (unstaged).
• Next step is the release commit + `<unit>-v<version>` tag + push.
• For workflow-wired units, the `release.yml` `tag-version-check` job verifies the unit's

CHANGELOG contains the tag version; if it doesn't, the release is blocked.

• For `vercel-ai-sdk`, publish manually with `scripts/publish-rc.sh` after the tag push; its

CHANGELOG is not workflow-gated yet.

Conventions

• **Date format**: `YYYY-MM-DD` in UTC.
• **Subsection order**: `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`, `### Security`. Omit empty subsections.
• **Sentinel**: `_No user-facing changes._` for a unit with no in-scope commits.
• **Keep `## [Unreleased]` at the top** — it stays empty between releases.

Why this exists

ADR