Changelog Basics

The Hook (The "Byte-Sized" Intro)

Nobody reads git log. Users want a clean, human-readable summary: what's new, what's fixed, what breaks. That's a changelog. It's the "What's New" section of your app update, but for developers. A well-maintained changelog saves users from guessing what changed and saves you from answering "what's different in this version?" on repeat.

📖 What is a Changelog?

A changelog is a file (typically CHANGELOG.md) that lists changes organized by version, following a consistent format. It's written for humans, not machines.

Conceptual Clarity

Standard changelog format (Keep a Changelog):

markdown

# Changelog

## [1.2.0] - 2026-02-13
### Added
- Dark mode support
- CSV export feature

### Fixed
- Login redirect loop (#167)

### Changed
- Updated dashboard layout

### Removed
- Deprecated `/api/v1` endpoints

## [1.1.0] - 2026-01-20
### Added
- User profile page

Change categories:

Category	When to Use
Added	New features
Changed	Modifications to existing features
Deprecated	Features marked for future removal
Removed	Previously deprecated features now removed
Fixed	Bug fixes
Security	Vulnerability patches

Real-Life Analogy

A changelog is like a building's renovation log: "January: added a new elevator. February: fixed the parking gate. March: removed the old staircase." Anyone can look at the log to understand what's changed.

Visual Architecture

flowchart TD VERSION["📦 v1.2.0"] --> ADDED["✅ Added"] VERSION --> FIXED["🔧 Fixed"] VERSION --> CHANGED["🔄 Changed"] VERSION --> REMOVED["🗑️ Removed"] VERSION --> SECURITY["🔒 Security"] style VERSION fill:#0f3460,stroke:#53d8fb,color:#53d8fb style ADDED fill:#1b2d1b,stroke:#53d8fb,color:#53d8fb style FIXED fill:#1a1a2e,stroke:#ffd700,color:#ffd700

Why It Matters

User trust: Users check changelogs before upgrading — it builds confidence.
Debugging help: When a bug appears, the changelog narrows when it was introduced.
Team alignment: Keeps everyone informed about what shipped in each version.
Open source standard: All major OSS projects maintain changelogs.

Code

bash

# ─── Generate changelog from git log ───
git log v1.1.0..v1.2.0 --oneline --no-merges
# Shows all commits between two releases

# ─── Format for changelog ───
git log v1.1.0..v1.2.0 --pretty=format:"- %s (%h)" --no-merges

# ─── Create the file ───
touch CHANGELOG.md
# Edit manually, grouping changes by category

# ─── Using conventional commits makes automation easy ───
# Commit messages like:
# feat: add dark mode
# fix: login redirect loop
# BREAKING CHANGE: remove v1 API
# These can be auto-grouped into categories

Key Takeaways

A changelog is a human-readable summary of changes per version.
Follow the Keep a Changelog format: Added, Changed, Fixed, Removed, Security.
Maintain CHANGELOG.md at the project root.
Conventional commit messages enable automatic changelog generation.

Interview Prep

Q: What is the difference between a changelog and git log? A: git log shows every commit including WIP, merge, and fixup commits. A changelog is a curated, human-readable summary organized by version and category (Added, Fixed, etc.). Changelogs are for users; git log is for developers.
Q: What format should a changelog follow? A: The widely-adopted "Keep a Changelog" format: organize by version, with subsections for Added, Changed, Deprecated, Removed, Fixed, and Security. Versions are listed newest-first with release dates.
Q: How do conventional commits help with changelogs? A: Conventional commits (e.g., feat:, fix:, BREAKING CHANGE:) use standardized prefixes that tools can parse to automatically categorize changes into the correct changelog sections.