Conventional Commits Standard Explained for Engineering Teams

Conventional Commits is a short specification that turns commit messages into release signals that tools can rely on. Its value comes from understanding the mechanism. Engineering teams that distinguish the standard’s requirements from local policy can connect commit history to version calculation, changelogs, and publishing without mistaking a naming convention for a complete release system.

What the Conventional Commits specification actually requires

Teams often say that all eleven commit types are required. The Conventional Commits Specification defines only two classification types, feat for new features and fix for bug fixes. Other types are optional. The familiar additions in @commitlint/config-conventional come from the Angular-derived convention. A team enforcing that larger vocabulary is enforcing a tooling policy on top of the standard.

A custom type can satisfy the specification yet fail the repository’s commitlint configuration. Conversely, allowing a type in configuration does not explain its meaning to contributors. The standard supplies a shared foundation, while the repository must document any vocabulary it adds.

The anatomy of a well-formed commit message

Every message starts with a required header. Its grammar is a type, an optional scope in parentheses, an optional exclamation mark, a colon, a single space, and a description. The description follows that separator immediately. An optional body follows a blank line, and optional footers are separated from the body by another blank line. Each part has a distinct role.

Consider the header feat(api)!: return 404 instead of 200 for a missing user. Here, feat identifies a new feature, (api) names the affected subsystem, and ! marks a breaking change. The text after the colon-space describes the change. A body would explain why the response changed rather than repeat the diff, while a BREAKING CHANGE footer would explain the compatibility impact and migration.

Tokens use hyphens in place of spaces, so Reviewed-by is valid and Reviewed by is invalid, while BREAKING CHANGE is the exception that keeps its space. Scope provides another useful distinction, as feat(parser) and feat(renderer) identify different subsystems without lengthening the description.

How commit types map to SemVer version bumps

The format becomes consequential when release tooling reads it. A fix maps to a release that increments the third version number, while a feat maps to a MINOR release. Any commit marked with ! or a BREAKING CHANGE footer maps to a MAJOR release, regardless of its type.

Nonbreaking docs, style, refactor, test, build, ci, and chore commits do not trigger releases under the conventional mapping described here. Those labels are not interchangeable with feature and fix labels. A bug correction labeled as a refactor can be left out of the release calculation even though the code change is still there.

An unstructured message creates the same kind of gap. A message such as “fixed stuff” does not provide the expected machine-readable signal, so an automated pipeline can omit a necessary version bump and leave the changelog incomplete.

The eleven conventional commit types and when to use each one

The default vocabulary distinguishes product behavior from supporting work. feat introduces a feature and triggers MINOR, as in feat(billing): add a yearly plan toggle. fix corrects a bug and triggers a patch release, as in fix(parser): handle multiple spaces in a string. perf improves performance and maps to a patch release, illustrated by perf(search): cache the tokenizer between calls. revert reverses a prior commit and maps to a patch release in this conventional release setup, as in revert: feat(billing): add a yearly plan toggle.

The remaining types do not ordinarily trigger a release. docs identifies documentation work, while style covers formatting and whitespace, as in style: run the formatter over the components folder. refactor changes code without fixing a bug or adding behavior, illustrated by refactor(auth): extract token refresh into a helper. test covers added or corrected tests, as in test(api): cover the retry path on a failed publish.

Build and workflow changes have separate labels too. build covers the build system or external dependencies, as in build(deps): bump esbuild to 0.23.1. ci covers CI configuration, illustrated by ci: run the test matrix on node 22. chore covers other changes that do not modify source or test files, such as chore: update the issue templates.

The practical distinction is what the change does. Added behavior belongs under feat, corrected behavior under fix, and improved speed without changed behavior under perf. A refactor must do neither of the first two. These release outcomes remain subordinate to a breaking-change marker, and the additional type mappings are tooling conventions rather than new requirements imposed by the specification.

Breaking changes: the exclamation mark, the footer, and what each one does

Breaking changes have two valid syntactic signals. The exclamation mark appears immediately before the header’s colon, as in feat(api)!: rename customer_id to client_id. It makes the compatibility break visible in a log view. The footer instead provides a dedicated description, such as BREAKING CHANGE: field renamed in all responses. Either form triggers a MAJOR bump.

The header provides visibility, while the footer supplies the migration explanation that changelog tooling can surface to consumers. An exclamation mark alone has no room for that multiline guidance, though some tools put the header summary in their breaking-changes section. The footer is not mandatory when ! is present.

A chore! or refactor! is valid when the change breaks downstream consumers, even if it adds no feature. Choosing a seemingly internal type does not neutralize a compatibility break. Its release consequence follows the marker.

Where the spec ends and your team's policy begins

A commitlint configuration without a contributing-guide entry is incomplete. The specification leaves scope rules, language, and type extensions to the team, so validation alone cannot explain the repository’s conventions. To close that gap, the policy should name valid scopes and state whether they follow directories, services, or domain boundaries. It should also say when scope is required and whether commitlint’s scope-enum rule enforces it or merely leaves it advisory.

Scope can support more than readable history. In a monorepo, distinctions such as feat(auth) and feat(payments) can support per-package changelogs and targeted CI triggers. The policy should also choose a language, with English recommended for tooling compatibility and international team legibility. Consistent language supports searching and onboarding.

Type extensions need the same explicit treatment. A team adding security or deps should include those types in both the contributing guide and the type-enum configuration. The policy should also establish one intent per commit. Tooling can validate the label’s syntax, but it does not automatically detect a commit that mixes unrelated purposes.

The three-layer enforcement stack: local hook, CI check, and release gate

Enforcement begins locally with commitlint and Husky. The setup uses @commitlint/cli, @commitlint/config-conventional, and husky, with a commit-msg hook that checks the message file at commit time. Invalid messages are blocked before entering history. However, this hook runs only on machines where contributors have installed it, so local enforcement cannot be the sole safeguard.

The second layer checks pull requests in CI. A workflow lints every commit on push, catching messages from contributors who skipped local setup. Squash merging introduces a separate enforcement hole because the PR title becomes the resulting commit message in that workflow. CI therefore needs to lint the title too. Validating individual commits does not validate a replacement title.

The release gate completes the stack with semantic-release or release-please, connecting structured history to version calculation. The latter also keeps track of the current version baseline in a manifest file. This layer should prevent nonconforming input from influencing a release. AI-generated messages belong under the same checks because they can contain invalid formats or omit required footers, although linting cannot establish whether an omitted migration explanation was semantically necessary.

How the structured commit history feeds automated changelog generation

An enforced history becomes a dataset for release communication. Teams can use three output layers from that shared source, with a technical changelog containing all commits for contributors, a public changelog filtering for features, fixes, performance improvements, and breaking changes, and a digest selecting highlights for distribution. Each layer serves a different reader. Documentation, maintenance, CI, formatting, and test changes can stay internal to keep user-facing changes clear.

The type filter therefore acts as an editorial filter. It separates changes users need to understand from work that primarily concerns maintainers, while preserving the underlying record. Structured categories also give AI writing tools cleaner input than an unstructured log, so they have a better starting point for release notes. A well-structured CHANGELOG.md serves both developers reading directly and AI assistants retrieving answers, making it communication material and retrieval infrastructure.

A malformed or misleading commit can suppress a needed bump or produce an inappropriate one, and the resulting changelog can misrepresent the release. Automatically written prose cannot fix that error in the commit.

What good public changelogs look like and why they matter to developer-tool teams

A public changelog can build trust and support product communication. Linear gives entries a headline, a concise two-to-four-sentence feature description, and a polished screenshot or GIF, while separate long-form posts cover design thinking. That separates the shipped change from its deeper explanation. Vercel uses major entries as launch material, adding video walkthroughs and technical deep dives. Resend is another public-changelog example to study, and these approaches need no ranking.

Consistent commits record what changed, while the writing and editing explain why a user should care. For lean teams, that separation reduces the work of discovering what shipped before writing about it. The public artifact need not resemble the raw log.

Filtered feature and fix commits can feed draft posts or digests, while merged pull requests and releases can act as content triggers. That allows a change’s story to be published the day it ships. A digest sent each week or with each release then keeps subscribers up to date on the product without the need for a separate editorial calendar.

When Conventional Commits is not worth the overhead

The standard does not justify its cost everywhere. A solo project with no package consumers and no automated releases gains little from formal enforcement. A project that never publishes a versioned artifact has no actionable output from the type-to-SemVer mapping. Short-lived repositories can also lose more to onboarding friction than they gain in lasting legibility. Those are legitimate reasons not to adopt it.

Data pipelines, infrastructure, and ML workflows may need types beyond the Angular-derived set, so teams have more to document and configure. At scale, an underspecified policy can produce inconsistent classifications despite syntactically valid messages.

Informal adoption can be worse than deliberate manual practice. Without commitlint and CI enforcement, apparent structure can invite automation that the history cannot reliably support. A team using careful manual versioning may produce more dependable release artifacts than one trusting a convention it does not enforce.

Adopting the standard incrementally without breaking existing workflows

A phased rollout avoids requiring a rewrite of history. The first phase is a CONTRIBUTING.md policy defining the type vocabulary, repository scopes, and language, starting with the eleven conventional types. The next phase adds commitlint and Husky, including setup instructions so contributors install the hook when cloning. CI enforcement comes next and checks both PR commits and PR titles. These checks can apply only to new commits from a chosen starting point.

Release automation should follow a clean release cycle. At that point, the team can connect semantic-release or release-please and treat the first automated release as a proof of concept. Manual inspection of its generated changelog should precede removing human sign-off. After a full cycle with enforcement in place, the changelog should be accurate without edits, and any corrections should lead the team to review the classification policy.

Consistent commit types also create a publishing trigger. A merged feature PR can supply the signal for a same-day post, with the structured history providing the starting material. Understanding the mechanism makes that downstream use dependable. The standard then supports not just release housekeeping, but the continuous communication of shipped work.