Changelog & Release Notes Craftsman: Transforming Git Commits into Customer Release Notes (2026)

The Changelog Dilemma: Why Raw Git Logs Look Amateurish

Shipping fast is essential, but writing release notes is the part everyone rushes. Too often that means the "release notes" are just the raw commit log: fix typo in header, wip auth, merge branch main into staging.

That obscures real progress from paying customers, confuses enterprise clients trying to figure out what changed, and, worse, fails to document breaking changes that quietly break someone else's integration.

The value of good release notes: they show engineering momentum, cut down support tickets from confused users, and build trust with the developers depending on your API.

The Keep a Changelog Standard

Release notes read better once they're sorted into fixed, predictable categories instead of dumped in commit order:

## [1.3.0] - 2026-08-26

### 🚀 Added
- **OAuth2 Social Authentication:** Native support for Google and GitHub single sign-on.
- **Webhook Event Dispatcher:** Real-time event notifications with exponential backoff retries.

### ⚡ Improved
- **Database Query Latency:** Faster large user pagination queries via keyset seeking.

### 🐛 Fixed
- Resolved race condition during concurrent JWT token refresh requests.

### ⚠️ Breaking Changes & Migration
- `client.getUser(id)` now returns a `Promise<UserResult>` instead of a raw object. Update calls to use `await client.getUser(id)`.

Sorting a commit into one of these buckets also makes it obvious which ones don't belong in the notes at all, fix typo, wip, and merge commits just get dropped.

Automated SemVer 2.0.0 Calculation

Version numbers can be derived from the actual diff instead of guessed:

• MAJOR (2.0.0): exported method signatures changed, endpoints removed, or database schemas altered.
• MINOR (1.3.0): backwards-compatible new features, optional parameters, or new endpoints added.
• PATCH (1.2.1): backwards-compatible bug fixes, security patches, performance work.

Generating Release Notes with Agent Skills

The Changelog & Release Notes Craftsman skill parses a git commit range, calculates the SemVer tag, and writes both the release notes and a social announcement in one pass:

"Using the changelog-release-craftsman skill, parse git commits since tag v1.0.0 and generate our v1.1.0 release notes, customer changelog, and Twitter announcement."

Frequently Asked Questions