Writing Better Commit Messages for Changelogs

Commit Messages That Make Great Changelogs

The quality of your generated changelog is directly proportional to the quality of your commit messages. Well-crafted commits produce changelogs that are useful to readers; poor commits produce noise.

The Anatomy of a Good Commit Message

feat(auth): add passwordless login with magic links

Part	Value	Purpose
Type	feat	Determines which section the change appears in
Scope	auth	Narrows the affected area for scannability
Description	add passwordless login with magic links	Explains the change for the reader

Writing Descriptions for Changelog Readers

Remember that commit messages become line items in the changelog. Write them for the person reading the release notes, not just for the developer reviewing the PR.

Avoid vague descriptions:

• fix: bug fix → Tells the reader nothing
• fix: update code → What code? What was the problem?

Be specific:

• fix(auth): resolve infinite redirect on expired sessions
• feat(search): add fuzzy matching with configurable threshold

Common Pitfalls

1. Missing type prefix — update user profile is not a valid Conventional Commit and will be skipped by the generator.
2. Overly broad scope — feat(app): everything defeats the purpose of scoping.
3. Inconsistent scopes — Using both auth and authentication for the same module creates fragmented changelog sections.
4. WIP commits — feat: wip or fix: temp should be squashed before generating the changelog.
5. Capitalization — Descriptions should start lowercase per the Conventional Commits spec.

Team Conventions

Establish and document your team's conventions:

• A defined list of valid scopes
• Description style (imperative mood: "add" not "added")
• When to use ! vs. BREAKING CHANGE footer
• Maximum description length (72 characters recommended)