You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
196 lines
4.0 KiB
196 lines
4.0 KiB
# 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
|
|
|