changelog

name	changelog
description	Use when the user asks to add a changelog entry, set up a `CHANGES.md` / `CHANGELOG.md` file, document user-facing changes in a release, or write a migration note for a breaking change. Triggers on phrases like "add to changelog", "CHANGES.md entry", "document this release", "release notes", "breaking change migration note", "what's new", "user-facing changes".

Changelog

When a changelog entry is required

• Add an entry when the PR results in user-visible changes (CLI behaviour changes, API additions/changes/removals, output format changes, config knobs added, defaults changed, dependencies bumped if they affect users).
• Add a migration note when the change is breaking — even inside a major-version bump.
• Skip when the PR is purely internal (refactor with no behaviour change, test additions, dev tooling changes).

What every entry must contain

Regardless of format:

• Version + date of the release the entry belongs to. Use the literal Unreleased (or equivalent) heading for changes not yet shipped — promote to a versioned heading at release time.
• One bullet per user-visible change, written from the user's perspective ("Added support for X", "Fixed crash when Y"). Not "Refactored Z". Prefer too much detail over too little — a reader six months from now should be able to act on the entry without re-reading the PR.
• PR or issue reference alongside each bullet (e.g. (#123)).
• Breaking changes clearly marked (e.g. a leading BREAKING: tag or a separate "Breaking changes" subsection), with migration guidance — inline if short, or a link to a longer migration doc.

For Haskell packages published to Hackage: ensure the file matches the package's changelog-file field in *.cabal (default CHANGELOG.md).

Format

If the repo already has a CHANGES.md / CHANGELOG.md: follow the existing format.

If the repo has no changelog yet: use the Keep a Changelog format. Its category vocabulary — use only categories you actually have content for, don't pre-stub empties:

• Added — new features.
• Changed — changes to existing functionality.
• Deprecated — soon-to-be-removed features.
• Removed — features removed in this release.
• Fixed — bug fixes.
• Security — vulnerability fixes.

Structural conventions:

• Version headings: ## [X.Y.Z] - YYYY-MM-DD.
• Unreleased changes live under a literal ## [Unreleased] heading at the top, no date. At release time, rename it to the new version + date and add a fresh [Unreleased] block above it.
• Category headings: ### Added, ### Fixed, etc. — one level deeper than the version.