Changelog Writing & Auditing

Use this skill when reviewing, drafting, or refining project changelogs. It ensures they follow Keep a Changelog formatting and remain clear to readers.

Core Rules

1. Write for Humans: Changelogs must be clear and readable. They are written for developers and users to understand what changed and why.
2. Do Not Dump Git Logs: Never export git commit messages directly into the changelog. Group and summarize changes into clear, user-facing actions.
3. Chronological Order: Group changes by version release, with the newest version at the top.
4. Link to Releases: Format version headers as links comparing the previous tag with the current tag when possible.

---

Standard Categories

Group changes under these third-level headers (###):

• ### Added: New features or capabilities.
• ### Changed: Improvements to existing behavior or APIs.
• ### Deprecated: Features that will be removed in future versions.
• ### Removed: Features removed in this release.
• ### Fixed: Bug fixes.
• ### Security: Vulnerability fixes or security upgrades.

---

Read Git History

Before updating a changelog, read the git history of the target branch:

1. Find Base Branch: Identify the base branch (e.g., main or the last release tag).
2. Get Commit Messages: Run git log <base-branch>..HEAD --oneline to see the commits. If checking local changes, use git log -n 50 --oneline.
3. Check Diff: If commit messages lack detail, run git diff <base-branch>..HEAD to see the code changes.
4. Summarize: Group changes under the standard Keep a Changelog categories. Translate commit messages into plain actions.

---

Tone and Style

• Plain Wording: Avoid corporate jargon or buzzwords. Use simple active verbs (e.g., "Use", "Simplify", "Improve", "Group").
• Active Voice: Start bullet points with past-tense action verbs (e.g., "Grouped 41 tools...", "Replaced format parameters...").
• Keep Lines Short: Use brief, single-sentence bullet points.

---

Examples

Bad Entry (Raw commit dump / AI-jargon)

## 1.1.0

- Refactored user authentication handlers to speed up login flow and collect performance metrics.
- We also resolved minor warnings.
- Added custom styling to dashboard panel.
- Fixed some bugs in the API request processor.

Good Entry (Keep a Changelog standard)

## 1.1.0

### Added
- Added custom styling properties to dashboard panels.

### Changed
- Simplified login flows in user authentication handlers.

### Fixed
- Fixed exception handling when processing API requests.

---

Checklist

Before saving a CHANGELOG.md file, verify:

• Version header uses ## [X.Y.Z] - YYYY-MM-DD format.
• Changes are grouped into standard subheadings (Added, Changed, Deprecated, Removed, Fixed, Security).
• No raw git commits or PR numbers dumped in text without explanation.
• Language is plain, direct, and free of AI buzzwords.
• Unreleased changes live under ## [Unreleased].