What is Conventional Commits?

Conventional Commits is a lightweight specification for writing commit messages in a structured, parseable format. Each commit starts with a type (like feat, fix, perf, or chore), an optional scope, and a short description. The format turns your git log from unstructured text into machine-readable data that downstream tools can use to generate changelogs, decide version bumps, and automate releases.

Why should my team adopt Conventional Commits?

The payoff is what becomes possible downstream — automated changelog generation, semantic versioning decisions, AI-powered release notes, and CI rules that react to commit type. The convention itself is a minor discipline, but it converts your commit history into structured data that powers the rest of your release workflow.

How do I enforce Conventional Commits on my team?

Install commitlint with the @commitlint/config-conventional preset, then add a Husky pre-commit hook or a CI check that rejects commits which don't match the convention. Setup takes about 15 minutes. After that, the tooling enforces the rules — no manual policing required.

Does Conventional Commits work with semantic versioning?

Yes — they're designed to pair. A fix commit implies a patch bump, a feat commit implies a minor bump, and a commit marked with ! or BREAKING CHANGE: implies a major bump. Tools like semantic-release and release-please use this mapping to compute the next version automatically from the commit history.

Will Conventional Commits make AI-generated release notes better?

Significantly. AI tools can summarize unstructured commits, but structured commits give the AI clear signal about which changes are user-facing features, which are bug fixes, and which are internal noise. The result is more accurate categorization, better headlines, and far less manual cleanup.

Conventional Commits: The Developer’s Guide to Better Changelogs

Conventional Commits is the simplest commitment you can make as a team that unlocks automated changelogs, semantic versioning, and cleaner git history. Here’s the complete guide to what it is, how to adopt it, and why it compounds over time.

If your team’s commit history reads like a stream of consciousness — wip, fix stuff, asdf, finally working, typo — you already know the problem. Finding when a specific change happened is archaeology. Writing release notes from that history is impossible. Automating anything downstream of commits is a nightmare.

Conventional Commits is the cheapest, lowest-commitment fix. It’s a small convention on how to format commit messages that turns your git log from unstructured text into structured data. Once you adopt it, everything downstream — changelogs, versioning, release notes, CI decisions — becomes automatable.

This guide covers exactly what Conventional Commits is, how to adopt it without breaking your team, and the automation it unlocks.

What Conventional Commits Is

Conventional Commits is a specification for writing commit messages that are parseable by tools. It was originally published as a lightweight standard that sits on top of Angular’s commit convention, and it’s now used by thousands of open source projects and internal teams.

The structure:

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

<optional body>

<optional footer>

The type is one of a small fixed set:

feat — a new feature
fix — a bug fix
docs — documentation-only changes
style — formatting, whitespace, no code change
refactor — code change that’s not a feature or a fix
perf — performance improvement
test — adding or updating tests
build — changes to build system or dependencies
ci — CI configuration changes
chore — other changes that don’t modify source or test files

The scope is optional and describes the part of the codebase affected: feat(api), fix(dashboard), refactor(auth).

The short description is one line, imperative mood, lowercase, no period.

A few real examples:

feat(export): add PDF format to dashboard exports
fix(webhook): retry failed deliveries up to 3 times
perf(db): reduce dashboard query time by batching
chore(deps): bump react from 18.2 to 18.3

Breaking changes are marked with a ! after the type or with a BREAKING CHANGE: footer:

feat(api)!: rename user.email to user.primaryEmail

BREAKING CHANGE: user.email has been renamed to user.primaryEmail.
Clients using user.email must update.

That’s the whole spec. Everything else is convention.

What It Unlocks

The payoff isn’t the commits themselves — it’s what becomes possible downstream.

Automated changelog generation. Tools can parse your commit history and produce a structured changelog grouped by type. feat commits go in the Features section, fix commits in Bug Fixes, breaking changes get their own prominent section.

Semantic versioning decisions. Conventional Commits maps directly to semantic versioning. A fix commit implies a patch version bump. A feat commit implies a minor version bump. A breaking change implies a major version bump. Tools can compute the next version from commits alone.

Release note generation via AI. Once commits are structured, feeding them into an AI tool to generate user-facing release notes becomes dramatically more reliable. The tool knows feat(dashboard): add PDF export is a feature to highlight and chore(deps): bump lodash is probably not.

CI decisions and alerts. Breaking changes can trigger different review requirements. Security-sensitive scopes can require specific sign-offs. All of this becomes possible when commit type is machine-readable.

Git history as documentation. Six months later, finding “when did we change how exports work” becomes grepping for feat(export) or fix(export) instead of reading 400 commit messages.

How to Adopt It Without Breaking Your Team

The biggest barrier to adoption isn’t the spec — it’s the social contract. Your team needs to agree to write commits differently, and inconsistent adoption is worse than no adoption.

Start with a lightweight enforcement mechanism. Install commitlint with the @commitlint/config-conventional preset. Add a Husky pre-commit hook or a CI check that runs commitlint against new commits. Now commits that don’t match the convention fail immediately — no remembering, no debating.

The setup is about 15 minutes. The payoff is that nobody has to police commits manually.

Teach the types once, not continuously. Put a short cheat sheet in your CONTRIBUTING.md or README. Hold a 15-minute team discussion to agree on scope names (this is the only genuinely ambiguous part). Then leave the tooling to enforce the rest.

Grandfather old history. You don’t need to rewrite existing commits. Start the convention from a specific date forward. Any automation you build can simply ignore commits before that date or treat them as unstructured.

Allow chore and refactor as escape hatches. Not every commit fits cleanly into a category. chore is the universal “this doesn’t affect users” bucket. Use it freely — it still contributes to the git log being scannable.

Common Objections (and the Responses)

“It’s too rigid. I don’t want to write imperative-mood commit messages all day.”

The rigidity is the point. Every time you think “is this a feat or a fix,” you’re spending two seconds thinking about what the change actually does. That’s cheap, and it prevents the accumulation of wip and stuff commits that make the log useless.

“Our team is too small to need this.”

Small teams benefit most, because small teams have less overhead to absorb chaos. A 2-person team with conventional commits can automate what a 10-person team with unstructured commits does manually.

“AI tools can already summarize unstructured commits.”

True, and they do a decent job. But structured commits let AI tools do a much better job. Giving an AI tool commits tagged feat vs chore means it knows which to surface and which to hide in the changelog. Without the tags, it has to guess.

“We already have a different convention.”

Fine. Conventional Commits isn’t sacred. Most of the benefit comes from any consistent convention, not specifically this one. If you have your own that works, keep it. The only requirement is that it’s machine-parseable.

Pairing Conventional Commits with Release Tooling

The most common automation stack built on top of Conventional Commits:

semantic-release / release-please. Tools that read conventional commits, determine the next version number automatically, generate a changelog, and cut the release. For many teams, this means releases happen automatically on merge to main, with zero manual steps.

AI-powered changelog tools. Tools like ReleasePad read your conventional commits (or pull requests, which are often even richer) and generate user-facing release notes. The commit convention gives the AI structured signal about what to highlight.

Custom scripts. For teams with specific needs, a 50-line script can parse conventional commits and emit a markdown changelog, a JSON feed, or a Slack notification. The investment is small, and you own the logic.

Whichever direction you go, the foundation is the same: a commit log that’s structured enough for automation.

What Conventional Commits Doesn’t Solve

Two specific limits worth naming.

It doesn’t improve commit content, only format. A commit titled feat: stuff is conventional but still useless. The convention enforces structure, not quality. Your team still has to care about clear descriptions.

It doesn’t replace pull request context. A PR description with context, screenshots, and user-facing explanation is still more useful than a conventional commit. For teams using PRs seriously, the PR is often the better source for changelog generation. Conventional commits work best when commits and PRs are both well-written, not as a substitute for good PRs.

Where to Start

If your team doesn’t already use a commit convention:

Agree on Conventional Commits (or a close variant) with the team.
Install commitlint with the conventional config.
Add a pre-commit hook or CI check.
Put a cheat sheet in the repo.
Start the convention from today forward.

That’s a one-afternoon project. The payoff compounds for every release, every changelog, every search through git history, every time you want to automate something downstream of commits.

Most teams that adopt this never go back. Not because the convention is beautiful — it’s a pretty minor discipline — but because the downstream automation is so much easier when the upstream data is structured. That’s the real reason to do it.

The commit log is the most underused structured dataset in your product. Conventional Commits is the cheapest way to start treating it like one.

ReleasePad turns your conventional commits — or your raw, messy ones — into clean, user-facing release notes automatically. Connect your GitHub repo, get AI-generated changelogs, a hosted page, and an in-app widget. Try it free →

Conventional Commits: The Developer's Guide to Better Changelogs