What is Conventional Commits?

Last reviewed May 28, 2026

Conventional Commits is a specification that adds a structured prefix to every git commit message — `feat:` for new features, `fix:` for bug fixes, `chore:` for routine work, plus an optional `BREAKING CHANGE:` footer for compatibility-breaking changes. The structure makes commit history machine-readable, which lets tools automatically generate changelogs, bump semantic version numbers, and trigger releases. Maintained by the open-source community at conventionalcommits.org and adopted by Angular, Yarn, and many other developer tools.

Example

A commit message like feat(api): add pagination to /users endpoint declares this is a new feature in the API surface. A tool like conventional-changelog, semantic-release, or Herald can parse the feat prefix to slot the entry into the "Added" or "New features" section of a release, and the optional BREAKING CHANGE: footer triggers a major-version bump in semver.

Why it matters

Without a convention, generating a changelog from git history requires manual triage of every commit — someone reads each PR title, decides what's customer-facing, picks a category, writes a user-friendly description. With Conventional Commits, the same generation is fully automatic. The investment is small (a one-line discipline at commit time) and the payoff is hours-per-release saved plus consistent release notes formatting forever.

More context

The full spec lives at conventionalcommits.org. The short version is a commit message shaped like:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The most common types you'll see in practice:

feat: — a new feature
fix: — a bug fix
chore: — routine maintenance (deps, formatting, etc.)
docs: — documentation only
refactor: — code change that neither adds a feature nor fixes a bug
perf: — performance improvement
test: — adding or correcting tests
build: / ci: — changes to build pipeline or CI

The BREAKING CHANGE: footer (or a ! after the type, e.g. feat!:) marks any change that requires consumers to update their code. This is the trigger for a major version bump under semantic versioning.

Conventional Commits doesn't require everyone on the team to be religious about it forever — even partial adoption gives you machine-readable history for the commits that follow the convention, and Herald (and similar tools) gracefully fall back to AI-drafting from PR titles and descriptions when commits aren't strictly conventional.

The downstream benefit is the killer feature: once your commit history is structured, tools can take over the work of writing changelogs, bumping versions, and triggering releases. That's the wedge Herald is built around — see Herald and GitHub Releases for the full read-PRs-and-publish-back-to-Releases workflow.

Related terms

Want to go deeper? Read Herald and GitHub Releases — when to use each.