# What is Conventional Commits?

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](https://github.com/conventional-changelog/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](https://www.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](https://semver.org).

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](/guides/herald-and-github-releases/) for the full read-PRs-and-publish-back-to-Releases workflow.

## Related terms

- [Changelog](/glossary/changelog/)
- [Release Notes](/glossary/release-notes/)
- [Breaking Change](/glossary/breaking-change/)

Deeper guide: [Herald and GitHub Releases — when to use each](/guides/herald-and-github-releases/)

Category: Developer Process
Last reviewed: 2026-05-28