Write Changelog

For every commit/PR, assign it to exactly one group:

Skip rules — do NOT include these in the changelog

When uncertain whether to include a change: if a user would notice the difference, include it. If they wouldn't, skip it.

Step 3 — Determine the audience and write accordingly

User-facing changelog (default)

Write from the user's perspective. Describe what changed for them, not what changed in the code.

• Bad: "Refactored the QueryBuilder class to use prepared statements"
• Good: "Fixed a bug where search queries with special characters returned no results"
• Bad: "Added maxRetries parameter to HttpClient"
• Good: "API requests now automatically retry on temporary failures (up to 3 attempts)"

Developer-facing changelog

Write from the developer's perspective. Include technical details, breaking changes, migration steps.

• Good: "Added maxRetries parameter to HttpClient constructor (default: 3). Set to 0 to disable."
• Good: "BREAKING: User.getProfile() now returns a Promise<Profile> instead of Profile. Update all call sites to use await."

Step 4 — Write each entry

Every changelog entry MUST follow these rules:

1. Imperative mood — "Add export feature" not "Added export feature" or "Adds export feature"
2. Start with a verb — "Fix," "Add," "Remove," "Change," "Improve," "Update"
3. One change per line — if a PR contains multiple changes, split them into separate entries
4. No ticket/PR numbers in the text — put references in parentheses at the end if needed: (#123)
5. Lead with the user impact — "Speed up dashboard loading by 40%" not "Optimize database queries"
6. Include breaking change warnings — prefix with **BREAKING:** and explain what to do

Step 5 — Assemble the changelog

Use this format:

## [version] — YYYY-MM-DD

### Added
- [entry]
- [entry]

### Changed
- [entry]

### Fixed
- [entry]

### Removed
- [entry]

### Security
- [entry]

Rules for assembly:

• Omit empty groups — if there are no Security changes, don't include the Security header
• Order groups: Added → Changed → Fixed → Removed → Deprecated → Security
• Within each group, order by impact (most significant first)
• If there are breaking changes, add a prominent section at the top:

### ⚠ Breaking changes
- **BREAKING:** [description and migration steps]

Step 6 — Version comparison summary

At the top of the changelog, include a brief summary:

**[version]** brings [N] new features, [N] fixes, and [N] improvements.
[One sentence highlighting the most significant change.]

If comparing two versions, include the diff stats:

**Comparing [old] → [new]**: [N] commits, [N] files changed, [N] contributors

Step 7 — Final checks

Before delivering, verify:

Rules

• When a single commit touches both user-visible and internal changes, only document the user-visible part.
• If the commit history is messy (no conventional commits, vague messages like "fix stuff"), read the actual diffs to understand what changed and write proper entries.
• If a bugfix and a feature are closely related (e.g., "add retry logic" could be a fix or a feature), classify based on whether the previous behaviour was a bug (→ Fixed) or just missing (→ Added).
• Security fixes should be described clearly enough for users to assess impact, but should not include exploitation details.
• For large changelogs (50+ entries), add a "Highlights" section at the top with the 3-5 most important changes.