CHANGELOG — Keeping a Good One

Also Known As

TL;DR

Explanation

A CHANGELOG.md (keepachangelog.com format) documents what changed per version for users consuming your code, not for git history consumers. Sections per release: Added, Changed, Deprecated, Removed, Fixed, Security. An Unreleased section accumulates changes for the next release. Each version section links to a tag diff. Changelogs are essential for open-source libraries — without one, consumers must read commit history to assess upgrade risk. Combined with Semantic Versioning, a clear changelog makes library upgrades significantly less risky and signals project maturity and maintainer diligence.

Common Misconception

Why It Matters

Common Mistakes

• Using git log as a changelog — commit messages are for developers, not users.
• Not following Keep a Changelog or semantic versioning conventions — inconsistent format is hard to parse.
• Forgetting to update the changelog before tagging a release — it is always stale.
• No distinction between Added, Changed, Deprecated, Removed, Fixed, Security sections.

Code Examples

# CHANGELOG.md anti-pattern:
## [Unreleased]
## [1.2.0] - 2026-03-01
- stuff
- fixes
- new things

# Structured changelog:
## [1.2.0] - 2026-03-01
### Added
- User export to CSV feature
### Fixed
- Session timeout not enforced on API endpoints
### Security
- Patched XSS in search results (CVE-2026-1234)

# CHANGELOG.md — Keep a Changelog format (keepachangelog.com)

## [Unreleased]
### Added
- PHP 8.3 typed class constants

## [2.4.1] - 2024-03-10
### Fixed
- Password reset tokens now expire after 1 hour (was never expiring)

### Security
- CVE-2024-XXXX: Patched XSS in user profile bio field

## [2.4.0] - 2024-02-28
### Added
- MFA support via TOTP
### Changed
- Session now regenerated on login (session fixation fix)
### Deprecated
- `UserManager::fetchCustomer()` — use `UserRepository::find()` instead
### Removed
- Removed legacy MD5 password migration path

## [2.3.0] - 2024-01-15
...

# Types: Added, Changed, Deprecated, Removed, Fixed, Security

References

• ↗ https://keepachangelog.com/en/1.1.0/

Tags

Related Terms