What is a conventional commit?
The Conventional Commits specification is a lightweight convention for commit messages that adds machine-readable meaning. The full format is:
<type>[optional scope][!]: <description>
[optional body]
[optional footer(s)]
Why use it
- Automated versioning. Tools like
semantic-release and changesets read your commits and bump the version automatically: fix = patch, feat = minor, breaking change = major.
- Auto-generated changelogs. Every release gets a clean, readable changelog without manual work.
- Filterable git history.
git log --grep="^feat" shows you every feature added since a tag.
- Onboarding. Newer team members read intent without needing institutional knowledge of every PR.
The most common types
feat — new user-facing functionality (minor bump)fix — bug fix to existing functionality (patch bump)docs — documentation onlyrefactor — rework without behavioral changetest — tests added or modifiedchore — tooling, deps, housekeepingperf — performance improvementci — CI pipeline / configbuild — build system or external dependenciesstyle — formatting, no semantic changerevert — reverts a prior commit
Description writing tips
- Use the imperative mood: add, remove, fix — not added, removed, fixes.
- Don't capitalize the first letter (matches the type style).
- No trailing period.
- Aim for 50-72 characters — GitHub truncates at 72.
- If you can't summarize it in 72 chars, the commit is probably doing too much.
Frequently Asked Questions
What is a conventional commit?+
A conventional commit is a commit message that follows the Conventional Commits 1.0 specification — a lightweight convention that adds human and machine readable meaning to commit messages. The format is: <type>[optional scope][!]: <description>, with optional body and footers.
Why use conventional commits?+
Conventional commits give you three concrete benefits: automated semver bumping (feat = minor, fix = patch, ! or BREAKING CHANGE = major), auto-generated changelogs via tools like semantic-release or changesets, and more readable git history that's filterable by intent.
How do I mark a breaking change?+
Two ways. Either add an exclamation mark after the type/scope (e.g., feat(api)!: drop support for Node 16), or add a BREAKING CHANGE: footer with a description of what broke. Both signals are recognized by semantic-release and similar tools. A breaking change bumps the major version in semver.
What's the difference between feat and fix?+
Feat introduces new functionality and bumps the minor version. Fix patches a bug in existing functionality and bumps the patch version. The rule of thumb: if it solves a reported defect, it's a fix; if it's new behavior users will benefit from, it's a feat.
Does this conventional commit builder work offline?+
Yes. The builder runs entirely in your browser using vanilla JavaScript. Once the page has loaded, you can disconnect and continue using it. No commit content is sent to any server.