Keep a Changelog — The Format Explained

What is Keep a Changelog?

Keep a Changelog is a set of conventions for writing changelogs. It was created to solve a common problem: most changelogs are either auto-generated commit dumps or completely absent. The format prioritizes humans over machines.

Guiding principles

1. Changelogs are for humans, not machines.
2. There should be an entry for every single version.
3. The same types of changes should be grouped.
4. Versions should be linkable.
5. The latest version comes first.
6. Release dates are shown for every version.

Change types

• Added — New features
• Changed — Changes in existing functionality
• Deprecated — Features that will be removed soon
• Removed — Removed features
• Fixed — Bug fixes
• Security — Vulnerability fixes

Full example

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- New webhook endpoint for real-time notifications

## [1.1.0] - 2026-03-15

### Added
- Dark mode support
- Email notifications for subscribers

### Fixed
- Widget loading issue on mobile Safari

## [1.0.0] - 2026-02-01

### Added
- Initial release with REST API
- Embeddable changelog widget
- Project management dashboard

Common anti-patterns

• Dumping git commits as your changelog — nobody wants to read that.
• Missing release dates — users need to know when changes happened.
• Linking to a diff instead of writing a summary — forces users to interpret raw code.
• No categories — makes it impossible to scan for relevant changes.

Keep a Changelog + Deplyd

Deplyd follows the Keep a Changelog philosophy while adding modern distribution: a 1.8KB embeddable widget, REST API for CI/CD integration, and email notifications so your users never miss an update.