Conventional Commits

Standardized commit message format for readable history and automated changelogs.

When This Skill Activates

• Creating git commits
• Reviewing commit message quality
• Generating changelogs
• Setting up commit hooks

Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Scope (Optional)

Indicates the area affected:

feat(auth): add OAuth2 login
fix(api): handle null response
refactor(contracts): extract base class

Common scopes:

• Component/module name
• contracts, frontend, api
• deps, config, ci

Subject Line Rules

• Imperative mood: "add" not "added" or "adds"
• Lowercase first letter
• No period at end
• Max 50 characters (72 hard limit)

Good:

feat(market): add limit order support
fix(vault): prevent double withdrawal
refactor(sdk): simplify type exports

Bad:

feat(market): Added limit order support.   # past tense, period
Fix vault bug                              # not specific
update stuff                               # vague

Body (Optional)

Explain the "why" when not obvious:

fix(settlement): handle edge case in payout calculation

The previous implementation failed when market resolved
to INVALID with partial fills. Now correctly refunds
the proportional collateral.

Breaking Changes

Use ! after type or BREAKING CHANGE: footer:

feat(api)!: change response format to v2

BREAKING CHANGE: Response now returns `data` wrapper.
Clients must update parsing logic.

Footer References

Link to issues/PRs:

fix(auth): resolve session timeout issue

Closes #123
Refs #456

Examples

Simple Feature

feat(orderbook): add price level aggregation

Bug Fix with Context

fix(crossing): prevent self-trade in atomic match

Orders from same address were incorrectly matching
against each other when prices crossed.

Closes #89

Refactor

refactor(contracts): extract shared validation logic

Move duplicate checks from Market and Vault into
BaseValidation contract.

Breaking Change

feat(sdk)!: require explicit chain ID in config

BREAKING CHANGE: chainId is now required in SDK init.
Auto-detection removed for security reasons.

Migration: Add chainId to your SDK configuration.

Chore/Dependencies

chore(deps): upgrade viem to 2.0

chore(ci): add gas snapshot to PR checks

Quick Reference

feat:     New feature (MINOR version bump)
fix:      Bug fix (PATCH version bump)
!:        Breaking change (MAJOR version bump)
docs:     Documentation
style:    Formatting
refactor: Code restructure
perf:     Performance
test:     Tests
chore:    Maintenance

Commit Hooks Setup

Add to .husky/commit-msg:

#!/bin/sh
npx commitlint --edit $1

Or with simple regex check:

#!/bin/sh
if ! grep -qE "^(feat|fix|docs|style|refactor|perf|test|chore|ci|revert)(\(.+\))?(!)?: .{1,50}" "$1"; then
  echo "Invalid commit message format"
  exit 1
fi

Changelog Generation

Commits automatically map to changelog: