{"id":"changelog","name":"changelog","summary":"Ratelリリース用にパッケージごとの CHANGELOG.md ファイルを更新してください。git-cliffでエントリをドラフトし(パッケージごとにスコープ化)、キュレーションできてからCHANGELOGを書きます。","body":"# /changelog\n\nUpdates a release unit's `CHANGELOG.md` in preparation for tagging it. Ratel releases\n**per unit** (ADR-0008): each unit ships on its own tag (`<prefix>-v*`) at its own version.\nFor workflow-wired units, `.github/workflows/release.yml` rejects a tag whose unit CHANGELOG\ndoesn't contain the version being released. `vercel-ai-sdk` is temporarily published\nmanually via `scripts/publish-rc.sh`; still run this skill before its tag even though the\nworkflow gate does not cover it yet.\n\nRun it **once per unit** you're releasing.\n\n## Release units it touches\n\nThe units and their manifests/CHANGELOGs live in one registry —\n`scripts/release-units.mjs` — which every release tool reads. Run `node scripts/release-units.mjs --list`\nfor the authoritative set; the current eight units are:\n\n| Unit | Registry | CHANGELOG path |\n|---|---|---|\n| `core` | `ratel-ai-core` (crates.io) | `src/core/CHANGELOG.md` |\n| `sdk-ts` | `@ratel-ai/sdk` (npm) | `src/sdk/ts/CHANGELOG.md` |\n| `sdk-py` | `ratel-ai` (PyPI) | `src/sdk/python/CHANGELOG.md` |\n| `telemetry-core` | `ratel-ai-telemetry` (crates.io) | `src/telemetry/core/CHANGELOG.md` |\n| `telemetry-ts` | `@ratel-ai/telemetry` (npm) | `src/telemetry/ts/CHANGELOG.md` |\n| `telemetry-py` | `ratel-ai-telemetry` (PyPI) | `src/telemetry/python/CHANGELOG.md` |\n| `vercel-ai-sdk` | `@ratel-ai/vercel-ai-sdk` (npm) | `src/adapters/ts-vercel-ai-sdk/CHANGELOG.md` |\n| `mastra` | `@ratel-ai/mastra` (npm) | `src/adapters/ts-mastra/CHANGELOG.md` |\n\n`@ratel-ai/mcp-server` lives in [ratel-ai/ratel-mcp](https://github.com/ratel-ai/ratel-mcp) and maintains its own CHANGELOG there.\n\n## Procedure\n\n### 1. Pick the unit and read its version\n\nIf the user hasn't named the unit, run `node scripts/releasable.mjs` — it lists which\nunits have commits since their last release tag. Pick the unit `$UNIT` being released.\n\nRead its canonical version:\n\n```bash\nnode scripts/release-units.mjs --version \"$UNIT\"   # -> $TARGET\n```\n\nIf the user supplies a different version explicitly, prefer that and warn them the working\ntree disagrees.\n\n### 2. Determine the diff range\n\nThe range is from the unit's **own** last release tag to `HEAD`:\n\n```bash\nprefix=$(node scripts/release-units.mjs --tag-prefix \"$UNIT\")\nFROM=$(git describe --tags --match \"${prefix}*\" --abbrev=0 2>/dev/null || true)\n```\n\nIf `$FROM` is empty the unit has never shipped; the whole history is in range.\n\n### 3. Generate the draft\n\n```bash\nbash .claude/skills/changelog/draft.sh --unit \"$UNIT\"\n```\n\nIt emits a single `### <package-name>` block for the unit, containing either\nKeep-a-Changelog sections (`### Added`, `### Fixed`, `### Changed`) or the sentinel\n`_No user-facing changes._`. (Omit `--unit` to draft every unit at once.) With no\n`<from-ref>` argument the script ranges each unit from its own last tag automatically.\n\nIf `draft.sh` exits 127, git-cliff is missing. Tell the user how to install it (the\nscript's stderr already does), and stop.\n\n### 4. Branch on RC vs GA\n\nInspect `$TARGET`, and edit only **this unit's** CHANGELOG:\n\n- **RC** (`X.Y.Z-rc.N`): prepend a new section above the most recent versioned section:\n  ```\n  ## [X.Y.Z-rc.N] - YYYY-MM-DD\n\n  <draft content for the unit, or the sentinel>\n  ```\n  Use today's date in `YYYY-MM-DD` (UTC).\n\n- **GA** (no `-rc` suffix): enter **GA-collapse mode**:\n  1. Find every `## [X.Y.Z-rc.*]` section already present that matches the same\n     `MAJOR.MINOR.PATCH` as `$TARGET`.\n  2. Union their bullet entries (per subsection: `### Added`, `### Changed`, `### Fixed`)\n     with the new draft entries from step 3 (commits since the last RC tag).\n  3. Deduplicate bullets within each subsection (case-insensitive, whitespace-normalised).\n  4. Drop the `_No user-facing changes._` sentinel if any real entries exist; keep it only\n     if the unioned set is empty.\n  5. Replace all the matched RC sections with a single `## [X.Y.Z] - YYYY-MM-DD` section\n     containing the merged content.\n  6. Leave non-matching prior versions (e.g. `## [0.1.4]`) untouched.\n\n### 5. Curate with the user\n\nShow the unit's CHANGELOG pending changes in the conversation. Ask the user to confirm or\nedit. Common curation moves:\n\n- Rephrase bullets for user-facing clarity (the draft uses commit subjects verbatim).\n- Drop bullets that are not user-visible (internal refactors that slipped past\n  `cliff.toml`'s skip rules).\n- Merge duplicates that survived deduplication.\n- Promote / demote between Added / Changed / Fixed if the commit prefix was wrong.\n\n### 6. Write the file\n\nOnce approved, write **only this unit's** CHANGELOG using the Edit tool. **Do not commit.**\nThe release commit is the user's responsibility — they typically include the CHANGELOG\nalongside the version bump in a single `release: <unit>-vX.Y.Z` commit.\n\nIf releasing more than one unit, repeat from step 1 for each.\n\n### 7. Remind\n\nTell the user:\n\n- The CHANGELOG is staged in the working tree (unstaged).\n- Next step is the release commit + `<unit>-v<version>` tag + push.\n- For workflow-wired units, the `release.yml` `tag-version-check` job verifies the unit's\n  CHANGELOG contains the tag version; if it doesn't, the release is blocked.\n- For `vercel-ai-sdk`, publish manually with `scripts/publish-rc.sh` after the tag push; its\n  CHANGELOG is not workflow-gated yet.\n\n## Conventions\n\n- **Date format**: `YYYY-MM-DD` in UTC.\n- **Subsection order**: `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`, `### Security`. Omit empty subsections.\n- **Sentinel**: `_No user-facing changes._` for a unit with no in-scope commits.\n- **Keep `## [Unreleased]` at the top** — it stays empty between releases.\n\n## Why this exists\n\nADR 0008 (`docs/adr/0008-release-engineering.md`) records the per-unit tag/version split, the\nCHANGELOG mechanism, and the rationale. Read it if you're unsure why something is structured\nthe way it is.","author":"@ratel-ai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/ratel-ai/ratel/tree/main/.claude/skills/changelog","license":"MIT","category":"coding","lang":"en","tokens":1623,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"draft.sh","size":2241,"sha256":"50f17d8b2bc7a0155abee34deba729c9f307c64ecd8016c769e608ba8f98ce6f"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":[]}}