keep-a-changelog

name	keep-a-changelog
description	Guidance for writing and editing CHANGELOG entries in the Keep a Changelog 1.1.0 style. Use when editing a CHANGELOG.md, adding a changelog entry for a change, writing release notes, or deciding which category (Added/Changed/Deprecated/Removed/Fixed/Security) a change belongs under.

Keep a Changelog entries

Guidance for writing notable-change entries in the Keep a Changelog 1.1.0 format. This skill is about writing entries, not creating changelog files or cutting releases.

A changelog is a curated, chronologically ordered list of notable changes, written for humans. Curate it — it is not a commit log.

Where entries go

Add new entries under the ## [Unreleased] section at the top of the file, grouped beneath a ### <Category> heading. Create the category heading if it isn't there yet.

## [Unreleased]

### Added

- New feature, described from the user's point of view.

### Fixed

- The bug that is now fixed, described by its observable symptom.

Each entry is a bullet (-). Newest version is at the top of the file; within a version, group bullets by category.

The six categories

Pick the category that matches the change's effect on the user. Use only these:

Category	Use for
Added	New features.
Changed	Changes in existing functionality.
Deprecated	Features soon to be removed.
Removed	Features now removed.
Fixed	Bug fixes.
Security	Vulnerabilities — what was vulnerable and that it's resolved.

If a change touches several categories, split it into one bullet per category rather than forcing it into one.

Writing a good entry

• Describe the user-visible change, not the implementation or the commit. "Hover documentation now shows the plugin's display name" — not "refactor DocProvider".
• Lead with the observable effect. For a fix, name the symptom that's gone; for a feature, name what the user can now do.
• One bullet per notable change. Keep each self-contained and readable on its own.
• Present tense, concise. Skip "this commit", "we", and ticket-speak.
• Match the house style of the file. This repo prefixes a bolded component then an em dash: **Navigation** — go to definition from a ref: to its id:. Follow whatever convention the surrounding entries already use.
• Link issues/PRs only when it helps the reader, never as a substitute for describing the change.
• Skip noise. Internal refactors, test-only changes, formatting, and dependency bumps that don't affect users generally don't belong in the changelog.

Anti-patterns to avoid

• No commit-log dumps. git log output is full of merge commits, obscure titles, and internal churn. Commits explain how the code evolved; changelog entries explain what changed for the user.
• Don't omit notable changes. A changelog that lists only some of the changes is as dangerous as none — users rely on it as the source of truth.
• Be painfully clear about breaking changes and deprecations. Users should be able to upgrade to a version that lists a deprecation, remove what's deprecated, then upgrade to the version where it's removed. Never let a breaking change go unmentioned.
• Use ISO 8601 dates (YYYY-MM-DD) wherever a date appears, e.g. ## [1.2.0] - 2026-06-29. Avoid region-ambiguous formats.