| name | changelog-format |
| description | Keep a Changelog format guidelines and entry writing best practices. Use when writing changelog entries, updating CHANGELOG.md, or following Keep a Changelog specification. |
| metadata | {"type":"reference"} |
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
