Conventional Commit Builder

Conventional Commits: a contract for your history

The Conventional Commits specification (v1.0.0, at conventionalcommits.org) is a lightweight convention on top of commit messages that originated around 2017 inside the Angular team and was later extracted into a standalone spec. Its goal is to turn the commit log into a machine-readable document so that tools can derive semantic versioning bumps, generate changelogs and trigger releases automatically — without anyone manually editing version numbers.

The shape is fixed: <type>[optional scope]: <description> on the first line, an optional blank-line-separated body, and an optional footer. A scope sits in parentheses right after the type to narrow the context, for example feat(auth): add OAuth flow. A breaking change is signaled either with a ! after the type/scope or with a BREAKING CHANGE: footer token.

feat(api): add pagination cursor

Returns a base64 cursor in the Link header.
Clients should stop relying on offset.

BREAKING CHANGE: offset query param removed
Refs: #482

The standard type vocabulary

• feat — a new feature for the user (bumps MINOR).
• fix — a bug fix for the user (bumps PATCH).
• docs — documentation-only changes.
• style — formatting, whitespace, missing semicolons; no behavior change.
• refactor — internal change that is neither a feature nor a fix.
• perf — performance improvement.
• test — adding or correcting tests.
• build, ci, chore, revert — tooling, pipeline, housekeeping and reverts (usually excluded from the changelog).

SemVer integration and release automation

Conventional Commits are designed to drive SemVer: a release containing at least one feat: becomes a MINOR bump, one with only fix: a PATCH, and any commit marked breaking forces a MAJOR. Tools like semantic-release, release-please (Google), standard-version and conventional-changelog read the log, compute the next version, tag the repository and publish a CHANGELOG.md grouped by type.

Linting and authoring tools

commitlint enforces the format locally via a Husky commit-msg hook, blocking malformed messages before they hit the remote. Commitizen (cz) replaces git commit with an interactive prompt that walks the author through type, scope, description and breaking-change flags. As an alternative aesthetic, gitmoji uses emojis (:sparkles:, :bug:) — it is popular but harder to automate against.

Style pitfalls

By convention the description is written in the imperative mood ("add", not "added" or "adds"), starts in lower case and does not end with a period. The scope, when present, has no whitespace and uses kebab-case. Body paragraphs are separated by blank lines and can include bullet points. Footers follow a Token: value format like git trailers (Refs:, Reviewed-by:, Closes:).

FAQ

How do I revert a commit correctly? Use the revert: type and reference the original commit hash in the body, e.g. revert: feat(api): add pagination cursor. Release tools recognize it and remove the entry from the upcoming changelog.

Does it work for monorepos and microservices? Yes — use the scope to identify the package or service (feat(billing-api):). Tools like Nx, Lerna and release-please support per-package versioning derived from the scope.

Is the convention too rigid for small teams? If the strict types feel heavy, you can either pick a smaller subset (just feat, fix, chore) or switch to gitmoji. The cost only pays off when there is real automation downstream.

Where do older conventions like [FEATURE] or [BUG] fit? They predate Conventional Commits and signal the same intent informally. Migrating to the spec is mostly a search-and-replace, but the real win is hooking up commitlint and a release tool — without those, the prefix alone adds little value.