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