CHANGELOG — Keeping a Good One
debt(d7/e3/b3/t7)
Closest to 'only careful code review or runtime testing' (d7). Tools like conventional-changelog, semantic-release, and keep-a-changelog can flag missing or malformed changelogs, but they require deliberate setup and CI integration — they won't catch quality issues like missing sections or stale entries automatically. The most common failure (no update before tagging) is only noticed during release review or when downstream users complain.
Closest to 'simple parameterised fix' (e3). The quick_fix is clear: add CHANGELOG.md to repo root, adopt Keep a Changelog format, and update per release. This is a small, localised effort — not a one-liner swap (e1) because it involves establishing a convention and possibly automating from conventional commits, but it doesn't span multiple files or components.
Closest to 'localised tax' (b3). The changelog applies to the project as a whole (web/cli contexts), but the burden is contained — one file, updated at release time. It doesn't shape architectural decisions or slow down day-to-day feature work. The tax is felt mainly at release time, not across every development task.
Closest to 'serious trap' (t7). The misconception field is explicit: developers assume 'git log reformatted = changelog', which contradicts the human-readable, grouped, impact-focused nature of a good changelog. This is a documented anti-pattern (common_mistakes confirm it) that contradicts how developers naturally think about version history, placing it at t7 — a serious trap that contradicts an obvious analogy from another familiar tool (git log).
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