Keep a Changelog Format

Keep a Changelog Format

This skill provides guidelines for writing and formatting changelogs following the Keep a Changelog specification.

Core Principles

1. Changelogs are for humans - Write for users, not machines
2. Every version gets a section - Including [Unreleased] for upcoming changes
3. Changes are grouped by type - Consistent categorization
4. Versions are linkable - Each version header links to comparison
5. Latest version comes first - Reverse chronological order
6. Release dates are shown - ISO format: YYYY-MM-DD

Change Categories

Use these categories in this order:

Category Guidelines

Added

• New user-facing features
• New API endpoints
• New configuration options
• New integrations

Changed

• Performance improvements
• UX/​UI changes
• Default value changes
• Behavior modifications

Deprecated

• Features planned for removal
• APIs being replaced
• Include migration path when possible

Removed

• Breaking changes (removed functionality)
• Deleted APIs or features
• Always note what replaced it (if applicable)

Fixed

• Bug corrections
• Error handling improvements
• Edge case fixes

Security

• Vulnerability patches
• Security-related fixes
• Always include CVE if available

Entry Writing Guidelines

Use Imperative Mood

Start entries with imperative verbs:

Focus on User Impact

Write from the user's perspective:

Be Specific and Concise

Include Context When Helpful

Use parenthetical context for clarity:

- Add OAuth2 support (Google, GitHub)
- Fix timezone handling (UTC offset calculation)
- Change rate limit (100 → 500 requests/​minute)

Changelog Structure

# Changelog

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

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

## [Unreleased]

### Added
- New entries go here

## [1.0.0] - 2024-01-15

### Added
- Initial public release
- Feature A with description
- Feature B with description

### Changed
- Improvement to existing feature

### Fixed
- Bug fix description

## [0.9.0] - 2024-01-01

### Added
- Beta release features

[Unreleased]: https://github.com/​owner/​repo/​compare/​v1.0.0...HEAD
[1.0.0]: https://github.com/​owner/​repo/​compare/​v0.9.0...v1.0.0
[0.9.0]: https://github.com/​owner/​repo/​releases/​tag/​v0.9.0

Semantic Versioning Connection

Changelog categories map to version bumps:

What NOT to Include

• Internal refactoring (unless it affects users)
• Dependency updates (unless they affect functionality)
• Test changes
• CI/​CD changes
• Documentation-only changes (unless user-facing docs)
• Code style/​formatting changes

Reference Files

• references/​entry-examples.md - Examples of well-written vs poorly-written entries