api-changelog-writer

---
name: api-changelog-writer
description: Writes an accurate API changelog entry from a diff. Use when the user asks to document a release, write release notes, or explain what changed in an API between versions.
---

# API changelog writer

## When to use this
A release needs notes, or the user asks what changed in an API between versions.

## Procedure
1. Read the actual diff. Never write a changelog from commit subjects alone —
   they describe intent, not effect.
2. Classify every change as **Breaking**, **Added**, **Changed**, **Deprecated**,
   **Removed**, or **Fixed**.
3. For each breaking change, write the migration in one sentence: what the caller
   must change, from what to what.
4. Derive the semver bump from the highest-severity class present, using the
   rules in [references/semver-rules.md](references/semver-rules.md).
5. Order the entry with breaking changes first.

## Rules
- Write for the caller, not the implementer. "Refactored the auth module" is not
  a changelog entry; "`login()` now returns `null` instead of throwing on bad
  credentials" is.
- Never invent a change that is not in the diff.
- If the diff contains no user-visible change, say so rather than padding.

# Deriving the version bump

| Change present | Bump |
| --- | --- |
| Any breaking change | major |
| New capability, fully backward compatible | minor |
| Fix only, no interface change | patch |

A deprecation on its own is a **minor** bump. Removing something previously
deprecated is **major** — deprecation is a warning, not a grace period that
converts a removal into a minor change.