Using Conventional Commits to power your changelog

If you want to generate a changelog from your Git history, structured commit messages make it far easier. The most common standard for this is Conventional Commits. This guide explains how Conventional Commits work, how they map to a changelog, and where the approach has limits.

What are Conventional Commits?

Conventional Commits is a lightweight convention for writing commit messages with a consistent, machine-readable prefix. The basic format is:

<type>(<optional scope>): <description>

For example:

feat(billing): add annual plan option
fix(auth): handle expired tokens gracefully

The common types

• feat — a new feature.
• fix — a bug fix.
• docs — documentation only.
• refactor — code changes that neither fix a bug nor add a feature.
• perf — performance improvements.
• chore — tooling and maintenance.

How it maps to a changelog

Because each commit is tagged with a type, a tool can group commits automatically:

• feat commits become Added entries.
• fix commits become Fixed entries.
• perf commits become Improved entries.

How it maps to versioning

Conventional Commits also drives semantic versioning:

1. A fix triggers a patch bump.
2. A feat triggers a minor bump.
3. A commit marked with BREAKING CHANGE triggers a major bump.

This lets you automate version numbers as well as the changelog.

Where it falls short

Conventional Commits produce a developer changelog. The output still reads like commit messages — accurate, but written for engineers. A customer doesn't want "feat(billing): add annual plan option"; they want "You can now save with annual billing."

Conventional Commits get you a structured log. They don't get you a readable story.

Bridging the gap

Changelog Generator takes the structured work in your repository — including the intent captured in pull requests — and rewrites it into a customer-facing update. You keep the rigor of Conventional Commits for your codebase and still ship a changelog people enjoy reading.