---
name: changelog-entry
description: Add a new entry to CHANGELOG.yml under the current unreleased version (or create the version block if needed), then regenerate documentation. Use when the user says things like "add a changelog entry", "log this fix in the changelog", or "/changelog-entry".
---

# changelog-entry

Adds an entry to `CHANGELOG.yml` following the schema documented in the file header, then regenerates the derived documentation.

## Inputs to gather (in order)

1. **type** — one of `bugfix`, `feature`, `security`, `change`. If the user describes the change but does not pick a type, infer it:
   - "fixes/resolves/closes a bug" → `bugfix`
   - "adds support for / introduces / new" → `feature`
   - "CVE / vulnerability / hardens" → `security`
   - anything else affecting behavior → `change`
2. **title** — short (≤80 chars), sentence-cased, no trailing period.
3. **body** — 2-3 sentences. **This field is HTML, not markdown.** Use `<code>...</code>` for code, `<a href="...">...</a>` for links. Prefer YAML's `>-` folded scalar so line wrapping doesn't leak literal newlines.
4. **docs** *(optional)* — path to a docs page under `docs/` if the entry deserves a "Learn more" link.
5. **image** *(optional)* — path under the `release-notes` directory if there's a visual.

## Steps

1. Read the top of `CHANGELOG.yml`. The first `items:` entry is the current/upcoming version.
2. If it has `date: (TBD)`, append the new entry to its `notes:` array.
3. If the top item is already dated (a shipped release), insert a NEW `- version: <next>` block above it with `date: (TBD)` and the single new note. Ask the user for the next version number — do not invent it.
4. Match existing indentation exactly (2 spaces). YAML is whitespace-sensitive.
5. After saving, run `make docs-files` to regenerate `docs/release-notes.md`, `docs/release-notes.mdx`, and `docs/variables.yml`. (The PostToolUse hook in `.claude/settings.json` will also try to do this; running it explicitly here makes the success/failure visible.)
6. Show the user the diff: `git diff CHANGELOG.yml docs/release-notes.md docs/release-notes.mdx docs/variables.yml`.

## Schema reference (from CHANGELOG.yml header)

```yaml
items:
  - version: 2.28.0
    date: (TBD)              # or YYYY-MM-DD
    notes:
      - type: bugfix         # bugfix | feature | security | change
        title: Short title
        body: >-
          Two or three sentences describing the change and why it
          is noteworthy.  This is HTML.
        docs: optional/path
        image: optional/path
```

## Things to avoid

- Do not edit `docs/release-notes.md`, `docs/release-notes.mdx`, or `docs/variables.yml` directly — they are generated.
- Do not include markdown syntax in `body`; it is rendered as HTML.
- Do not set `date:` to a concrete date for upcoming versions; `make prepare-release` does that automatically for GA versions.