Conventional Commits

Conventional Commits (a.k.a. semantic commit messages)

A commit convention that makes history machine-readable: a parser reads each message, decides the next semver version, and builds the changelog from it. "Semantic commits" is the common nickname for the same thing. It's the foundation the release automation stands on — [semantic-release-automation](../semantic-release-automation/SKILL.md) covers the tooling that consumes these messages.

The format

[()][!]: 

• type / scope: lowercase by convention — the spec is case-insensitive,

except BREAKING CHANGE, which MUST be uppercase. scope is an optional noun in parens for the area touched.

• ! before the colon or a BREAKING CHANGE: footer marks a breaking change

(BREAKING-CHANGE: with a hyphen is an accepted synonym).

• description: concise; by convention imperative mood, lowercase, **no

trailing period** (Angular/commitlint style — the spec itself mandates none of these).

• Blank line before any body/footer.

feat(auth): add passkey sign-in
fix(parser): handle empty input without throwing
feat(api)!: drop the v1 token endpoint
docs: fix typo in install steps

Types → meaning → version bump

These are the semantic-release defaults (the angular preset plus commit-analyzer's built-in release rules). They're configurable via releaseRules, but treat them as the contract.

| Type | Use for | Default release | | --- | --- | --- | | feat | a new feature | minor (x.Y.0) | | fix | a bug fix | patch (x.y.Z) | | perf | performance improvement | patch | | docs, style, refactor, test, build, ci, chore | maintenance, no user-facing behaviour change | no release on their own | | revert | revert a previous commit | patch (the change is being undone) | | any type with ! / BREAKING CHANGE: | incompatible change | major (X.0.0) |

The "no release" types still belong in history — the tooling just won't cut a version for them alone. A release containing only chore/docs commits produces no new version, which is usually correct.

Breaking changes

Either form triggers a major bump and a highlighted changelog section:

feat(api)!: require auth on all routes

…or via a footer (works on any type, and lets you explain the migration):

refactor(db): rename users.email column

BREAKING CHANGE: `users.email` is now `users.email_address`; update queries.

Scopes

Optional, but meaningful: a noun naming the area (fix(toggle): …). In a monorepo the scope is how releases/changelogs are routed per package — repos often require it (e.g. feat(web-app): …, feat(react-typed-form-kit): …). Keep a scope vocabulary documented so it stays consistent.

Squash merges: the PR title is the commit

With squash merging (the common modern setup), the PR title becomes the single commit message on main — so the PR title must be a valid Conventional Commit, or the release/changelog step sees a non-conventional message and skips it. Put the individual semantic commits in the squash body for detail. [git-trunk-branch-and-pr-automation](../git-trunk-branch-and-pr-automation/SKILL.md) covers the CI that enforces this.

> Caveat: the title only becomes the commit when the repo's squash setting is > "Default to pull request title". With GitHub's out-of-the-box "Default > message", a single-commit PR reuses that commit's message instead of the > title — so a non-conventional lone commit still skips the release even though the > PR title looks fine. Set the repo to default to the PR title, or keep the single > commit conventional too.

• Single-package repo: the title's scope is optional.
• Monorepo: scope the title to the package, and keep a PR to one package

where practical — a squash collapses everything to one type+scope, so a multi-package PR applies the same bump to all and muddies per-package changelogs.

Writing good ones

• Imperative mood: "add", not "added"/"adds" (it completes "this commit will…").
• Keep the subject short: the spec sets no limit; commitlint defaults to 100 chars

and Git display favours ~72 — match the project's commitlint config. The body explains why, not what.

• One logical change per commit. If a change is genuinely both a feature and a

fix, split it; if you can't, the type reflects the highest-impact change (a feat that also fixes something is feat).

• Reference issues in the footer: Closes #123, Refs: ABC-12.

Gotchas

• Non-conventional → silently no release. A typo'd type or a prose subject is

ignored by the analyzer: no bump, no changelog entry. This is the #1 "why didn't it release / why is the changelog blank?" cause — check the merge commit / PR title first.

• Don't hand-write chore(release): … commits. Those are produced by the

release bot; writing one yourself can confuse tooling (and such commits are often CI-skipped deliberately).

• Issue IDs in the subject can misbehave. A Linear/Jira key like ABC-123 in

the subject may auto-transition the ticket or render oddly in changelog links; some setups keep IDs in the footer or de-link them (ABC-123 → ABC - 123) in the generated changelog.

• Revert format: a header revert: plus a

body line This reverts commit . — that body line is what the parser keys on. The semantic-release parser is case-insensitive and also matches git's default Revert "" header, so an untouched git revert commit is recognised — but commitlint / PR-title validators reject Revert as a type, so lowercase the header to revert: to pass those. Reverts default to a patch release.

Verify

• Lint locally or in CI with commitlint (@commitlint/config-conventional), or

validate PR titles with a PR-title action (see [git-trunk-branch-and-pr-automation](../git-trunk-branch-and-pr-automation/SKILL.md)).

• Confirm the intended bump with a semantic-release dry run

(npx semantic-release --dry-run) — it prints the next version and release notes without publishing.

See also

Companion skills in this set:

• [semantic-release-automation](../semantic-release-automation/SKILL.md) — turns

these commits into versions, a changelog, and GitHub releases.

• [git-trunk-branch-and-pr-automation](../git-trunk-branch-and-pr-automation/SKILL.md)

— branch naming + squash + the PR-title validation that enforces this format.

Sources

• Conventional Commits 1.0.0 — grammar, the ! / BREAKING CHANGE rules, the

BREAKING-CHANGE hyphen synonym, and case-insensitivity (except BREAKING CHANGE, which must be uppercase):

• semantic-release commit-analyzer default release rules (angular preset) —

feat→minor, fix/perf→patch, breaking→major, revert→patch, every other type → no release:

• The type list and per-package scope rules also match conventions enforced in

production repos (a production app's PR-title validator allows feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert; a production monorepo requires per-package scopes).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stealth-engine
• Source: stealth-engine/skills
• License: MIT

Install and usage instructions live in the source repository linked above.