Conventional Commits to Changelog: The Complete Guide

Conventional Commits is one of the best things to happen to release notes in years. By adding a simple prefix to each commit message — feat:, fix:, breaking: — you give your version control system enough structure to automatically generate a high-quality changelog. This guide walks through exactly how that works, from the spec itself to a fully automated changelog pipeline.

What is Conventional Commits? It's a lightweight specification for structuring commit messages. Each commit starts with a type keyword followed by a colon and a description. The most common types are: feat (a new feature), fix (a bug fix), docs (documentation changes), refactor (code restructuring), perf (performance improvements), and breaking or the ! suffix for breaking changes.

A commit message like 'feat: add CSV export to reports' tells you two things immediately: it's a new feature, and it adds CSV export. A changelog generator can read that prefix, categorise it under 'New Features,' and format the description for users. No guessing, no manual triage.

Why it matters for changelogs. Without a commit convention, generating a changelog means reading every commit, deciding what category it belongs in, and rewriting it for users. That's tedious and error-prone. With Conventional Commits, the category is encoded in the commit itself. The generator just reads the prefix and maps it.

The mapping is straightforward: feat commits go into New Features, fix commits go into Bug Fixes, perf commits go into Improvements, breaking commits go into Breaking Changes (usually at the top, where they belong). This structure lets readers scan your changelog and find exactly what matters to them.

Setting up your team. Getting started with Conventional Commits is simple, but getting consistent adoption takes a little effort. First, document the convention in your team's contributing guide. Second, add a commit message template using a tool like commitlint or a Git hook that validates the format. Third, lead by example — when senior engineers use the convention, the rest of the team follows.

You don't need perfect compliance. Even if 70% of your commits follow the convention, a changelog generator can categorise those automatically and flag the rest for manual review. The 30% of unconventional commits are usually chores, merges, or work-in-progress messages that don't belong in the changelog anyway.

From commits to changelog. Once your team is using Conventional Commits, generating a changelog is a matter of parsing the commit range and mapping types to categories. Here's what that looks like in practice:

You run your changelog generator against the range of commits since your last release — for example, everything between v2.3.0 and v2.4.0. The generator reads each commit message, extracts the type prefix, and groups commits accordingly. Merge commits and noise get filtered out automatically.

The output is a structured changelog with clear sections: New Features lists every feat commit, Bug Fixes lists every fix commit, Improvements captures perf and refactor commits, and Breaking Changes is highlighted at the top. Each entry is the commit description, cleaned up and formatted for readability.

Automating the pipeline. The final step is to run this automatically as part of your release process. When you tag a new version, a script can generate the changelog, save it as a markdown file or publish it to your changelog page, and even create a GitHub Release with the notes pre-filled. This is where the real time savings appear — your changelog writes itself at release time, with zero manual intervention.

Tools like ReleaseCast handle this end-to-end. You paste your commit range, and it parses Conventional Commits, categorises everything, and produces a clean changelog you can publish immediately. It works even if your commits aren't perfectly conventional — it does its best to categorise and lets you review.

Common pitfalls. A few things trip teams up. First, don't overuse the breaking flag — reserve it for changes that genuinely break existing functionality. Second, write commit descriptions that make sense to users, not just to you at 2am. 'feat: add dark mode' is great. 'feat: stuff' is not. Third, keep your scope consistent — if you use feat for user-facing features, don't suddenly use it for internal refactoring.

Conventional Commits is the foundation of modern changelog automation. Once your commits are structured, everything downstream — categorisation, formatting, publishing — becomes automatic. It's one of the highest-leverage practices a development team can adopt, and the payoff compounds with every release. For real-world inspiration, browse our collection of open source changelog examples that get it right.