Writing Changelogs

Overview

Changelogs follow the Keep a Changelog specification (v1.1.0) for human-readable release documentation.

Core principle: Changelogs are for humans, not machines. Curate meaningful changes—don't dump git logs.

When to Use

• Creating initial CHANGELOG.md
• Releasing a new version (moving Unreleased to versioned section)
• Adding entries to Unreleased section after completing work
• User says "update changelog", "document changes", "prepare release"

NOT for: Commit messages (use making-git-commits skill)

Changelog Format

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.2.0] - 2025-12-26

### Added
- User authentication with OAuth 2.0 support

### Changed
- Improve error messages for validation failures

### Fixed
- Handle null responses in API client gracefully

[Unreleased]: https://github.com/owner/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0

Change Categories

Note: docs, test, build, ci, chore commits typically don't appear in changelogs unless user-facing.

Mapping Commits to Changelog

Conventional Commit → Changelog Entry

feat(auth): add OAuth 2.0 support
→ ### Added
  - OAuth 2.0 authentication support

fix(api): handle null response gracefully
→ ### Fixed
  - Handle null responses in API client gracefully

feat(config)!: require explicit environment variable
→ ### Changed
  - **BREAKING:** CONFIG_PATH environment variable now required

Writing Good Entries

Do:

• Write for end users, not developers
• Start with verb: "Add", "Fix", "Remove", "Change"
• Explain impact, not implementation
• Group related changes in single entry
• Link to issues/PRs when helpful: ([#42](link))

Don't:

• Copy commit messages verbatim
• Include internal refactoring details
• Use technical jargon unnecessarily
• List every commit

# ❌ Bad: Technical, commit-style
- refactor(utils): consolidate date formatting functions
- fix(parser): handle edge case in tokenizer line 847

# ✅ Good: User-focused
- Improve date formatting consistency across the application
- Fix parsing errors when input contains special characters

Release Workflow

1. REVIEW: Check commits since last release
2. CATEGORIZE: Group by Added/Changed/Deprecated/Removed/Fixed/Security
3. CURATE: Write human-readable entries (not commit dumps)
4. VERSION: Move Unreleased to new version section with date
5. LINKS: Update comparison links at bottom
6. VERIFY: Ensure date is ISO 8601 (YYYY-MM-DD)

Quick Reference

Guiding Principles

1. Changelogs are for humans — Write prose, not code
2. Entry for every version — No gaps in history
3. Group same types — All Added together, all Fixed together
4. Versions are linkable — Use reference-style links
5. Latest first — Reverse chronological order
6. Show release dates — ISO 8601 format always
7. Follow SemVer — State this in header

Common Mistakes

Red Flags - STOP

• About to paste raw git log into changelog
• Including chore:, ci:, test: commits directly
• Writing for developers instead of users
• Forgetting to update comparison links
• Using non-ISO date format
• Missing categories for different change types
• No Unreleased section for ongoing work

Creating Initial CHANGELOG.md

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.1.0] - YYYY-MM-DD

### Added
- Initial release with core functionality

[Unreleased]: https://github.com/owner/repo/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/owner/repo/releases/tag/v0.1.0

The Bottom Line

Changelogs tell the story of your project for humans.

A good changelog answers: "What changed and why should I care?"

Don't let your friends dump git logs into changelogs.