kjanat Changelog Writing
Write changelogs for humans, not machines. Follow the Keep a Changelog convention.
Format Rules
- File:
CHANGELOG.mdat 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:
| Category | Use for |
|---|---|
Added |
New features |
Changed |
Changes to existing functionality |
Deprecated |
Features marked for future removal |
Removed |
Features removed in this release |
Fixed |
Bug fixes |
Security |
Vulnerability patches |
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
| Don't | Why |
|---|---|
| Dump git log as changelog | Noise: merge commits, docs changes, typos |
| Skip deprecation notices | Users can't prepare for breaking changes |
| Use regional date formats | Ambiguous (01/02/03). Use ISO 8601 |
| Document only some changes | Partial changelog is worse than none |
| Use GitHub Releases alone | Non-portable, less discoverable than a file |
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
| Task | Files to Read |
|---|---|
| Create new CHANGELOG | SKILL.md + example.md |
| Add release entries | SKILL.md (categories) |
| Review format | SKILL.md (format rules) |
| See full example | example.md |
In This Reference
| File | Purpose |
|---|---|
| example.md | Complete example changelog |