Conventional Commits Builder

Why follow a commit convention

Conventional Commits is a lightweight specification for commit messages that makes them machine-readable. Once your team uses it consistently, you can automate things that are otherwise tedious: generate changelogs from commit history, determine the next semantic version automatically (major bump on breaking changes, minor on feat, patch on fix), filter releases by change type, and easily find when a specific kind of change was introduced.

The full spec lives at conventionalcommits.org. The short version: every commit starts with a type, optionally a scope, and a brief subject. Body and footer are optional. The format is strict enough for tools to parse, loose enough that humans don't hate it.

The standard types

• feat — a new user-facing feature. Triggers a MINOR version bump in semver-release tools.
• fix — a bug fix. Triggers a PATCH version bump.
• docs — documentation-only changes. No version bump.
• style — whitespace, formatting, missing semicolons. No version bump. (Not about CSS!)
• refactor — code restructure that doesn't change behavior. No version bump.
• perf — performance improvement that doesn't change behavior. Triggers a PATCH bump.
• test — adding or fixing tests. No version bump.
• build — changes to build system or external dependencies.
• ci — changes to CI configuration files and scripts.
• chore — maintenance tasks that don't fit the categories above (deps update, repo housekeeping).
• revert — reverts a previous commit.

Breaking changes

A breaking change (API change, removed feature, behavior modification that requires consumers to update) is marked in two complementary ways:

# Option 1: ! after the type/scope
feat(api)!: remove deprecated /v1/users endpoint

# Option 2: BREAKING CHANGE: footer
feat(api): consolidate user endpoints

BREAKING CHANGE: /v1/users has been removed.
Use /v2/users instead. Response format unchanged.

Use both for clarity. Semver-release tools see either marker and bump the MAJOR version. This tool emits both when you check the "Breaking" box.

Subject line rules that matter

• Imperative mood. "add search shortcut" — not "added", not "adds", not "adding". Pretend you're completing the sentence "If applied, this commit will ___". Git's own commits use this style.
• Lowercase. No capitalization at the start. (Unless the first word is a proper noun.)
• No period at the end. The subject is a label, not a sentence.
• Under 72 characters. Some tools truncate beyond that; git log --oneline works best when subjects fit on one terminal line.
• Specific over generic. "fix login bug" — bad. "fix: prevent 500 on empty password" — good. Three months later, "login bug" tells you nothing.

Enforcing this in your repo

# commitlint + husky setup
npm i -D @commitlint/config-conventional @commitlint/cli husky
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
npx husky init
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

# Test it
git commit -m "broken"           # rejected
git commit -m "feat: add foo"    # accepted

Once set up, every commit is validated before it lands. New contributors get an instant rejection with a clear explanation when they don't follow the format — much better than discovering in a PR review.