Conventional commit builder

What is a Conventional Commit Builder?

Conventional Commits is a lightweight specification for commit messages that makes history readable and machine-parsable. Tools like semantic-release, release-please and standard-version read these messages to decide the next version number and generate changelogs automatically. This builder assembles a correctly formatted message from its parts.

How to use it

  1. Choose the type, such as feat or fix.
  2. Optionally add a scope, such as auth or api.
  3. Write a short description in the imperative mood.
  4. Add a body, a breaking change note and footers such as issue references if needed.
  5. Copy the message into git commit.

Format

type(scope)!: description

body

BREAKING CHANGE: explanation
Refs: #123

Example

feat(auth): add passkey login

Users can now sign in with WebAuthn passkeys.

Closes #482

Common types and version impact

  • feat: a new feature, triggers a minor release.
  • fix: a bug fix, triggers a patch release.
  • feat! or BREAKING CHANGE: triggers a major release.
  • docs, style, refactor, perf, test, build, ci, chore: no release by default in most configurations.

Writing good descriptions

  • Use the imperative: add, not added or adds.
  • Keep the first line under about 72 characters.
  • Explain why in the body, not just what.
  • Enforce the format in CI with commitlint.

Frequently Asked Questions

What is a Conventional Commit?

A commit message following the format type(scope): description, which lets tools generate changelogs and version numbers automatically.

How do I mark a breaking change?

Add an exclamation mark after the type or scope, or add a footer starting with BREAKING CHANGE followed by a description.

Is the scope required?

No. The scope is optional and usually names the area of the codebase affected.

Which tools use Conventional Commits?

semantic-release, release-please, standard-version, commitlint and many changelog generators.

What is the difference between chore and refactor?

refactor changes production code without changing behaviour, while chore covers maintenance that does not touch source code, such as updating dependencies or build scripts.

You May Also Need