Write and maintain changelogs following the Keep a Changelog convention. Use when creating a CHANGELOG.md, adding entries for a release, or reviewing changelog format and completeness.
Write changelogs for humans, not machines. Follow the Keep a Changelog convention.
CHANGELOG.md at project rootYYYY-MM-DD)Group changes under these headings, in this order:
| Category | Use for |
|---|---|
Added | New features |
Changed | Changes to existing functionality |
Deprecated | Features marked for future removal |
Removed | Features removed in this release |
Fixed | Bug fixes |
Security | Vulnerability patches |
Omit empty categories. Never invent new category names.
Always keep an ## [Unreleased] section at the top:
## [Unreleased]
### Added
- New user profile endpoint.
At release time, move Unreleased entries into a new versioned heading.
## [1.2.0] - 2025-08-15
Yanked releases append [YANKED]:
## [1.1.0] - 2025-07-01 [YANKED]
At the bottom of the file, define diff links for every version:
[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0
| Don't | Why |
|---|---|
| Dump git log as changelog | Noise: merge commits, docs changes, typos |
| Skip deprecation notices | Users can't prepare for breaking changes |
| Use regional date formats | Ambiguous (01/02/03). Use ISO 8601 |
| Document only some changes | Partial changelog is worse than none |
| Use GitHub Releases alone | Non-portable, less discoverable than a file |
| Task | Files to Read |
|---|---|
| Create new CHANGELOG | SKILL.md + example.md |
| Add release entries | SKILL.md (categories) |
| Review format | SKILL.md (format rules) |
| See full example | example.md |
| File | Purpose |
|---|---|
| example.md | Complete example changelog |