Keep a Changelog format

Contract

When producing a CHANGELOG file or release notes, label and order every entry with the exact Keep a Changelog vocabulary and layout below. Apply this whenever the task is "write/update a changelog", "draft release notes", or "turn these commits into a changelog" — even if the user doesn't name the format.

Rules

The six section headings (exact words, exact order)

Group entries under these SIX headings only, spelled EXACTLY like this, as level-3 ### headings, in THIS order. Omit a heading when it has no entries — never reorder, never rename, never invent a seventh:

1. ### Added — new features and capabilities. NOT "Features", "New Features", "New",

"Additions".

1. ### Changed — changes to existing behavior, including performance work, tuning,

renames, and refactors. NOT "Updated", "Improvements", "Enhancements", "Changes", "Performance", "Renamed".

1. ### Deprecated — features still present but marked for future removal. NOT

"Deprecations", "Obsolete".

1. ### Removed — features deleted in THIS release. NOT "Deletions", "Dropped",

"Deleted", "Breaking".

1. ### Fixed — bug fixes. NOT "Bug Fixes", "Fixes", "Bugfixes", "Patches".
2. ### Security — vulnerability fixes and security hardening. NOT "Security Fixes",

"Vulnerabilities". Never fold a security issue under Fixed.

Each entry is a Markdown list item (- ...) under its heading.

Layout

• Start the file with a # Changelog title (level-1). An intro line is optional.
• Put a ## [Unreleased] section at the very top, above every released version, for

merged-but-unshipped work. When the user gives no version/date, everything goes here.

• Write each released version header as ## [X.Y.Z] - YYYY-MM-DD: the version in

square brackets, then a space, a hyphen, a space, then an ISO 8601 date.

• List released versions in reverse-chronological order — newest version first, oldest

last. When inserting a new release, place it above all existing ones.

• Mark a pulled/retracted release by appending [YANKED] to its version header:

## [1.5.0] - 2026-11-20 [YANKED].

Date normalization

Convert every date to ISO 8601 YYYY-MM-DD. This includes spelled-out, slashed, day-first, and ordinal dates:

• "June 26, 2026" → 2026-06-26
• "06/26/2026" and "2026/06/26" → 2026-06-26
• "7 Feb 2026" and "Aug 2, 2026" → 2026-02-07, 2026-08-02
• "the thirty-first of January 2026" / "October 5th, 2026" → 2026-01-31, 2026-10-05

Conventional-commit mapping

When the input is commit messages (feat:, fix:, perf: …), map type → section:

| Commit type | Section | |--------------------|---------------| | feat | Added | | fix | Fixed | | perf, refactor | Changed | | revert | Removed | | docs, style, test, chore, ci, build | omit (not user-facing) |

A security-relevant fix still goes under Security, not Fixed.

Worked examples

Added (not "Features")

BEFORE:

### Features
- OAuth login

AFTER:

### Added
- OAuth login

Changed — performance counts as Changed (not "Improvements"/"Performance")

BEFORE:

### Performance Improvements
- Search index is 3x faster

AFTER:

### Changed
- Search index is 3x faster

Deprecated (not "Deprecations")

BEFORE:

### Deprecations
- v1 REST endpoints (removal next year)

AFTER:

### Deprecated
- v1 REST endpoints (removal next year)

Removed (not "Dropped"/"Deletions")

BEFORE:

### Dropped
- Legacy XML parser

AFTER:

### Removed
- Legacy XML parser

Fixed (not "Bug Fixes")

BEFORE:

### Bug Fixes
- Crash on logout

AFTER:

### Fixed
- Crash on logout

Security — never fold under Fixed

BEFORE:

### Fixed
- SQL injection in the report builder
- Off-by-one in pagination

AFTER:

### Security
- SQL injection in the report builder

### Fixed
- Off-by-one in pagination

Version header + ISO date

BEFORE:

## 2.1.0 (June 26, 2026)

AFTER:

## [2.1.0] - 2026-06-26

Reverse-chronological order

BEFORE (oldest first):

## [1.0.0] - 2026-01-01
## [1.1.0] - 2026-06-01

AFTER (newest first):

## [1.1.0] - 2026-06-01
## [1.0.0] - 2026-01-01

Unreleased bucket

BEFORE:

## [0.0.0] - TBD
### Added
- Dark-mode toggle

AFTER:

## [Unreleased]
### Added
- Dark-mode toggle

YANKED release

BEFORE:

## [1.5.0] - 2026-11-20 (pulled — data-loss bug)

AFTER:

## [1.5.0] - 2026-11-20 [YANKED]

Edge cases & exceptions

• No version or date yet → put the work under ## [Unreleased]. Do not invent a

version number or a date.

• A "fix" that closes a vulnerability → Security, not Fixed. Security wins.
• A rename (e.g. "Projects" → "Workspaces") → Changed, not a new "Renamed"

heading.

• Performance / refactor work → Changed. There is no "Performance" heading.
• A brand-new project's first release → still opens with # Changelog; pre-1.0

work with no version goes under ## [Unreleased].

• Empty section → omit it entirely; don't emit ### Removed with nothing under it.
• Brackets are mandatory on both [Unreleased] and every [X.Y.Z] — even the

first release.

Do / Don't

• Always write ### Added; never ### Features or ### New Features.
• Always write ### Fixed; never ### Bug Fixes.
• Always write ### Changed for perf/refactor/rename; never ### Improvements or

### Performance.

• Always put security under ### Security; never fold it into ### Fixed.
• Always wrap the version in square brackets: ## [2.1.0] - ...; never bare ## 2.1.0.
• Always render the date as YYYY-MM-DD; never leave "June 26, 2026" or "06/26/2026".
• Always list newest version first; never oldest-first.
• Always mark a pulled release [YANKED]; never silently delete it.

Common mistakes (the base's wrong defaults)

• Reaching for GitHub's auto-generated "Features / Bug Fixes / Performance

Improvements" headings instead of the six canonical ones.

• Folding security fixes into Fixed.
• Writing the version header as ## 2.1.0 or ## v2.1.0 without brackets.
• Leaving prose dates ("June 26, 2026") instead of ISO 2026-06-26.
• Listing versions oldest-first, or appending a new release at the bottom.
• Inventing a placeholder version/date instead of using [Unreleased].
• Creating ad-hoc headings like "Renamed", "Deprecations", or "Dropped".

Quick checklist

• ] Headings are exactly Added / Changed / Deprecated / Removed / Fixed / Security.
• ] Headings appear in that canonical order; empty ones omitted.
• ] File opens with # Changelog; ## [Unreleased] sits on top.
• ] Each version header is ## [X.Y.Z] - YYYY-MM-DD with brackets.
• ] Every date is ISO 8601.
• ] Versions are newest-first.
• ] Security separate from Fixed; pulled releases marked [YANKED].