# Commit Message Format and Templates

> **Agent role**:
  Reference this file for commit message formatting and templates.

## Commit Message Format (Normative)

### A. Subject Line (required)

```

<type>(<scope>)<!>: <summary>

```

- **type** (lowercase, Conventional Commits):

  `feat|fix|refactor|perf|docs|test|build|chore|ci|revert`

- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)

- **!**: include when a breaking change is introduced

- **summary**: imperative mood, ≤ 72 chars, no trailing period

**Examples**

- `fix(api): handle null token in refresh path`

- `feat(ui/login)!: require OTP after 3 failed attempts`

### B. Body (optional, when it adds non-obvious value)

- One blank line after subject.

- Wrap at ~72 chars.

- Explain **what** and **why**, not line-by-line "how".

- Include brief notes like tests passing or TS/lint issues resolved

  **only if material**.

**Body checklist**

- [ ] Problem/symptom being addressed

- [ ] High-level approach or rationale

- [ ] Risks, tradeoffs, or follow-ups (if any)

### C. Footer (optional)

- Issue refs: `Closes #123`, `Refs #456`

- Breaking change (alternative to `!`):

  `BREAKING CHANGE: <impact + migration note>`

- Authors: `Co-authored-by: Name <email>`

- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)

## Content Guidance

### Include (when relevant)

- Specific fixes/features delivered

- Symptoms/problems fixed

- Brief note that tests passed or TS/lint errors resolved

### Avoid

- Vague: *improved, enhanced, better*

- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,

  focused commits if needed)

- Redundancy: generic blurbs repeated across files

- Multi-purpose dumps: keep commits **narrow and focused**

- Long explanations that good inline code comments already cover

**Guiding Principle:** Let code and inline docs speak. Use commits to
highlight what isn't obvious.

## Copy-Paste Templates

### Minimal (no body)

```text

<type>(<scope>): <summary>

```

### Standard (with body & footer)

```text

<type>(<scope>)<!>: <summary>

<why-this-change?>
<what-it-does?>
<risks-or-follow-ups?>

Closes #<id>
BREAKING CHANGE: <impact + migration>
Co-authored-by: <Name> <email>

```

## Type Descriptions

### feat

New feature for the user

### fix

Bug fix for the user

### docs

Documentation only changes

### style

Changes that do not affect the meaning of the code

### refactor

Code change that neither fixes a bug nor adds a feature

### perf

Code change that improves performance

### test

Adding missing tests or correcting existing tests

### build

Changes that affect the build system or external dependencies

### ci

Changes to CI configuration files and scripts

### chore

Other changes that don't modify src or test files

---

**See also**:

- `.cursor/rules/workflow/version_control.mdc` for

  core version control principles

- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details

**Status**: Active commit message guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: version_control.mdc
**Stakeholders**: Development team, AI assistants

## Model Implementation Checklist

### Before Creating Commits

- [ ] **Change Review**: Review all changes to be committed
- [ ] **Scope Assessment**: Determine if changes belong in single or multiple commits
- [ ] **Message Planning**: Plan clear, descriptive commit message
- [ ] **Convention Check**: Review commit message format requirements

### During Commit Creation

- [ ] **Type Selection**: Choose appropriate commit type (feat, fix, docs, etc.)
- [ ] **Message Writing**: Write clear, concise commit message
- [ ] **Body Content**: Add detailed description if needed
- [ ] **Breaking Changes**: Document breaking changes with `!` and migration notes

### After Commit Creation

- [ ] **Message Review**: Verify commit message follows conventions
- [ ] **Change Validation**: Confirm all intended changes are included
- [ ] **Documentation**: Update any related documentation
- [ ] **Team Communication**: Communicate significant changes to team
