Keep a Changelog Format

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

Core Principles

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

Change Categories

Use these categories in this order:

| Category | Description | When to Use | |----------|-------------|-------------| | Added | New features | New functionality users can now do | | Changed | Changes in existing functionality | Behavior modifications, improvements | | Deprecated | Soon-to-be removed features | Features marked for future removal | | Removed | Removed features | Features that no longer exist | | Fixed | Bug fixes | Corrections to existing functionality | | Security | Security vulnerability fixes | Security-related changes |

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:

| Do | Don't | |----|-------| | Add support for... | Added support for... | | Fix crash when... | Fixed a crash that occurred when... | | Remove deprecated... | Removed the deprecated... | | Change default to... | Changed the default to... |

Focus on User Impact

Write from the user's perspective:

| Good (User-focused) | Bad (Implementation-focused) | |---------------------|------------------------------| | Add dark mode toggle | Implement ThemeProvider context | | Fix login failing silently | Add try-catch to auth handler | | Speed up page load by 40% | Optimize database queries |

Be Specific and Concise

| Good (Specific) | Bad (Vague) | |-----------------|-------------| | Fix crash when uploading files over 10MB | Fix upload bug | | Add CSV export for transaction history | Add export feature | | Change session timeout from 30 to 60 minutes | Update session settings |

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:

| Category | Version Impact | |----------|----------------| | Removed (after v1.0) | MAJOR bump | | Removed (before v1.0) | MINOR bump | | Added, Changed | MINOR bump | | Deprecated, Fixed, Security | PATCH bump |

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