Changelog Writing

Write changelogs for humans, not machines. Follow the Keep a Changelog convention.

Format Rules

• File: CHANGELOG.md at project root
• Date format: ISO 8601 (YYYY-MM-DD)
• Latest version first (reverse chronological)
• One entry per version, every version documented
• Follow Semantic Versioning
• Version headings are linkable (comparison URLs at bottom)

Change Categories

Group changes under these headings, in this order:

Omit empty categories. Never invent new category names.

Unreleased Section

Always keep an ## [Unreleased] section at the top:

## [Unreleased]

### Added

- New user profile endpoint.

At release time, move Unreleased entries into a new versioned heading.

Version Heading Format

## [1.2.0] - 2025-08-15

Yanked releases append [YANKED]:

## [1.1.0] - 2025-07-01 [YANKED]

Comparison Links

At the bottom of the file, define diff links for every version:

[Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/org/repo/releases/tag/v1.1.0

Anti-Patterns

Writing Style

• Write entries as imperative statements from the user's perspective
• Focus on what changed for the user, not implementation details
• Be specific: "Add dark mode toggle in settings" not "Update UI"
• Group related changes into a single entry when appropriate

Reading Order

In This Reference