Commit Messages

Every commit in this monorepo is validated against the Conventional Commits specification. The check is wired into a husky commit-msg hook that runs commitlint against the message you just wrote — if the message does not match the rules, the commit is rejected and nothing is written to history.

The format

1
type(scope): short description
2
 
3
[optional body]
4
 
5
[optional footer]

• type — one of the prefixes listed below. Required.
• scope — optional free-form hint at what area of the code is affected (e.g. ui, gateway, docs). Wrapped in parentheses.
• short description — imperative mood, lower-case, no trailing period. Think "add button variant", not "Added a Button variant."
• body / footer — optional. Use the body to explain why the change was made. Use footers for BREAKING CHANGE: notices or issue references.

The repo extends @commitlint/config-conventional, so the default conventional-commit rules apply (subject length, non-empty subject, lower-case type, etc.) on top of the custom type-enum defined below.

Allowed types

Passing examples

A well-formed conventional commit looks like this:

1
feat(ui): add compact density to DataTable

Scope is optional — skip it when the change is cross-cutting:

1
docs: document the commit message convention

Longer message with a body explaining why:

1
fix(gateway): strip HTML from search snippets
2
 
3
The WP REST API returns rendered HTML in `excerpt.rendered`.
4
Passing that straight to the search index broke highlight ranges
5
in the docs search modal.

A refactor with no behavioural change:

1
refactor(ui): extract Button variant config into cva factory

A variant tweak using the monorepo-specific variant type:

1
variant(ui): tighten Hero spacing on the compact variant

Failing examples

Each failing example below is followed by the exact error commitlint prints when the commit is rejected. The ⧗ input: line echoes your message, and the ✖ line explains what broke.

Missing type

1
added a new button variant

1
⧗   input: added a new button variant
2
✖   subject may not be empty [subject-empty]
3
✖   type may not be empty [type-empty]
4
 
5
✖   found 2 problems, 0 warnings
6
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
7
 
8
husky - commit-msg script failed (code 1)

Commitlint cannot parse a subject at all because there is no type: prefix, so both type-empty and subject-empty fire.

Unknown type

1
feature(ui): add compact density to DataTable

1
⧗   input: feature(ui): add compact density to DataTable
2
✖   type must be one of [feat, fix, chore, ci, docs, refactor, test, variant, style, perf, build, revert] [type-enum]
3
 
4
✖   found 1 problems, 0 warnings
5
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
6
 
7
husky - commit-msg script failed (code 1)

feature is not in the allowed list — use feat instead.

Upper-case type

1
Feat(ui): add compact density to DataTable

1
⧗   input: Feat(ui): add compact density to DataTable
2
✖   type must be lower-case [type-case]
3
✖   type must be one of [feat, fix, chore, ci, docs, refactor, test, variant, style, perf, build, revert] [type-enum]
4
 
5
✖   found 2 problems, 0 warnings
6
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
7
 
8
husky - commit-msg script failed (code 1)

@commitlint/config-conventional enforces lower-case types, and type-enum matches case-sensitively — so Feat trips both rules.

Empty subject

1
chore:

1
⧗   input: chore:
2
✖   subject may not be empty [subject-empty]
3
 
4
✖   found 1 problems, 0 warnings
5
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
6
 
7
husky - commit-msg script failed (code 1)

A type without a subject is not a message — describe what you actually did.

How the hook runs

The commit-msg hook is a one-liner:

1
npx --no -- commitlint --edit $1

$1 is the path to the temporary file that git uses to hold your message. --edit tells commitlint to read from that file, and --no makes npx refuse to fetch commitlint from the network — it must already be installed locally (it is, via the root package.json devDependencies). If the hook exits non-zero, git aborts the commit before it is written to history.

Fixing a rejected commit

When the hook rejects your message, git has not created the commit yet — your staged changes are still staged. Just run git commit again with a corrected message:

1
git commit -m "feat(ui): add compact density to DataTable"

If you had already opened the editor and written a long body, use:

1
git commit --edit

to re-open the last attempted message in your editor and fix it in place.

What not to do

• Do not bypass the hook with --no-verify. It exists for a reason — see the git hooks guide for why skipping hooks is actively discouraged in this repo.
• Do not pad types onto a non-conforming message just to make the hook happy (chore: fix stuff). Pick the type that matches reality.
• Do not use past tense (fix: fixed button). Conventional commits use imperative mood: fix: fix button hover state.

Related

• Branch naming — the sibling convention for branch names.
• Git hooks — the full tour of husky hooks, including why --no-verify is off-limits.