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
- Write for Humans: Changelogs must be clear and readable. They are written for developers and users to understand what changed and why.
- Do Not Dump Git Logs: Never export git commit messages directly into the changelog. Group and summarize changes into clear, user-facing actions.
- Chronological Order: Group changes by version release, with the newest version at the top.
- 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:
- Find Base Branch: Identify the base branch (e.g.,
main or the last release tag).
- Get Commit Messages: Run
git log <base-branch>..HEAD --oneline to see the commits. If checking local changes, use git log -n 50 --oneline.
- Check Diff: If commit messages lack detail, run
git diff <base-branch>..HEAD to see the code changes.
- 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:
1---
2name: changelog-writing
3description: Use when authoring, auditing, or updating CHANGELOG.md files to adhere strictly to Keep a Changelog and Semantic Versioning standards.
4metadata:
5 platforms: "cross-platform"
6 languages: "generic"
7 category: "git"
8---
9
10# Changelog Writing & Auditing
11
12Use this skill when reviewing, drafting, or refining project changelogs. It ensures they follow Keep a Changelog formatting and remain clear to readers.
13
14## Core Rules
15
161. **Write for Humans**: Changelogs must be clear and readable. They are written for developers and users to understand what changed and why.
172. **Do Not Dump Git Logs**: Never export git commit messages directly into the changelog. Group and summarize changes into clear, user-facing actions.
183. **Chronological Order**: Group changes by version release, with the newest version at the top.
194. **Link to Releases**: Format version headers as links comparing the previous tag with the current tag when possible.
20
21---
22
23## Standard Categories
24
25Group changes under these third-level headers (`###`):
26
27* `### Added`: New features or capabilities.
28* `### Changed`: Improvements to existing behavior or APIs.
29* `### Deprecated`: Features that will be removed in future versions.
30* `### Removed`: Features removed in this release.
31* `### Fixed`: Bug fixes.
32* `### Security`: Vulnerability fixes or security upgrades.
33
34---
35
36## Read Git History
37
38Before updating a changelog, read the git history of the target branch:
391. **Find Base Branch**: Identify the base branch (e.g., `main` or the last release tag).
402. **Get Commit Messages**: Run `git log <base-branch>..HEAD --oneline` to see the commits. If checking local changes, use `git log -n 50 --oneline`.
413. **Check Diff**: If commit messages lack detail, run `git diff <base-branch>..HEAD` to see the code changes.
424. **Summarize**: Group changes under the standard Keep a Changelog categories. Translate commit messages into plain actions.
43
44---
45
46## Tone and Style
47
48* **Plain Wording**: Avoid corporate jargon or buzzwords. Use simple active verbs (e.g., "Use", "Simplify", "Improve", "Group").
49* **Active Voice**: Start bullet points with past-tense action verbs (e.g., "Grouped 41 tools...", "Replaced format parameters...").
50* **Keep Lines Short**: Use brief, single-sentence bullet points.
51
52---
53
54## Examples
55
56### Bad Entry (Raw commit dump / AI-jargon)
57```markdown
58## 1.1.0
59
60- Refactored user authentication handlers to speed up login flow and collect performance metrics.
61- We also resolved minor warnings.
62- Added custom styling to dashboard panel.
63- Fixed some bugs in the API request processor.
64```
65
66### Good Entry (Keep a Changelog standard)
67```markdown
68## 1.1.0
69
70### Added
71- Added custom styling properties to dashboard panels.
72
73### Changed
74- Simplified login flows in user authentication handlers.
75
76### Fixed
77- Fixed exception handling when processing API requests.
78```
79
80---
81
82## Checklist
83
84Before saving a `CHANGELOG.md` file, verify:
85
86* [ ] Version header uses `## [X.Y.Z] - YYYY-MM-DD` format.
87* [ ] Changes are grouped into standard subheadings (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`).
88* [ ] No raw git commits or PR numbers dumped in text without explanation.
89* [ ] Language is plain, direct, and free of AI buzzwords.
90* [ ] Unreleased changes live under `## [Unreleased]`.
dhruvanbhalara