# 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** (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: ` - Authors: `Co-authored-by: Name ` - Security: `CVE-XXXX-YYYY: ` (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 (): ``` ### Standard (with body & footer) ```text (): Closes # BREAKING CHANGE: Co-authored-by: ``` ## 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