175 lines
4.4 KiB
Markdown
175 lines
4.4 KiB
Markdown
---
|
|
name: conventional-commits
|
|
description: "Format git commit messages following Conventional Commits 1.0.0 specification. Use when the user asks to commit changes, create a git commit, or mentions committing code. Ensures consistent, semantic commit messages that support automated changelog generation and semantic versioning."
|
|
license: MIT
|
|
---
|
|
|
|
# Conventional Commits
|
|
|
|
Format all git commit messages according to the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/) specification.
|
|
|
|
## Commit Message Format
|
|
|
|
```
|
|
<type>[optional scope]: <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
## Type Reference
|
|
|
|
| Type | When to Use | SemVer |
|
|
|------|-------------|--------|
|
|
| `feat` | New feature | MINOR |
|
|
| `fix` | Bug fix | PATCH |
|
|
| `docs` | Documentation only | - |
|
|
| `style` | Formatting, whitespace (no code change) | - |
|
|
| `refactor` | Code restructuring (no feature/fix) | - |
|
|
| `perf` | Performance improvement | - |
|
|
| `test` | Adding/fixing tests | - |
|
|
| `build` | Build system, dependencies | - |
|
|
| `ci` | CI/CD configuration | - |
|
|
| `chore` | Maintenance, tooling | - |
|
|
| `revert` | Reverting previous commit | - |
|
|
|
|
## Decision Framework
|
|
|
|
When determining commit type, ask:
|
|
|
|
- Does it add new functionality? → `feat`
|
|
- Does it fix broken functionality? → `fix`
|
|
- Does it only affect documentation? → `docs`
|
|
- Does it improve performance? → `perf`
|
|
- Does it restructure code without changing behavior? → `refactor`
|
|
- Does it only change code style/formatting? → `style`
|
|
- Does it add/modify tests? → `test`
|
|
- Does it change build system or dependencies? → `build`
|
|
- Does it change CI/CD configuration? → `ci`
|
|
- Is it maintenance or tooling? → `chore`
|
|
|
|
## Message Best Practices
|
|
|
|
### Description (first line)
|
|
- Keep under 50 characters
|
|
- Use imperative mood ("add" not "added")
|
|
- Don't capitalize first letter
|
|
- No period at end
|
|
|
|
### Scope
|
|
- Use clear, consistent names: `feat(auth):`, `fix(api):`, `docs(readme):`
|
|
|
|
### Body
|
|
- Include when change requires explanation
|
|
- Explain why the change was made
|
|
- Describe what problem it solves
|
|
- Wrap at 72 characters per line
|
|
|
|
### Footers
|
|
- `Fixes #123` - Reference issues
|
|
- `Co-authored-by: Name <email>` - Credit contributors
|
|
- `BREAKING CHANGE: description` - Breaking changes
|
|
- `Refs: #456, #789` - Related issues
|
|
|
|
## Breaking Changes
|
|
|
|
Indicate breaking changes using either method:
|
|
|
|
```
|
|
feat!: remove deprecated API endpoint
|
|
|
|
feat(api)!: change authentication flow
|
|
|
|
fix: update validation logic
|
|
|
|
BREAKING CHANGE: validation now rejects empty strings
|
|
```
|
|
|
|
## Command Execution
|
|
|
|
**Critical**: Use single quotes to avoid shell escaping issues with `!`:
|
|
|
|
```bash
|
|
# Correct - single quotes
|
|
git commit -m 'feat!: add new authentication flow'
|
|
|
|
# Incorrect - backslash escaping (DO NOT USE)
|
|
git commit -m "feat\!: add new authentication flow"
|
|
```
|
|
|
|
For multi-line messages, use HEREDOC:
|
|
|
|
```bash
|
|
git commit -m "$(cat <<'EOF'
|
|
feat(auth): add OAuth2 support
|
|
|
|
Implement OAuth2 authentication flow with support for
|
|
Google and GitHub providers.
|
|
|
|
BREAKING CHANGE: removes legacy session-based auth
|
|
EOF
|
|
)"
|
|
```
|
|
|
|
## Workflow
|
|
|
|
1. Check for staged changes: `git diff --cached --stat`
|
|
2. If nothing staged: stage with `git add` first
|
|
3. Review changes: `git diff --cached`
|
|
4. Check recent style: `git log --oneline -5`
|
|
5. Determine type using decision framework
|
|
6. Write message following best practices
|
|
7. Execute commit with single quotes
|
|
8. Verify: `git log -1`
|
|
|
|
## Quality Checks
|
|
|
|
Before committing, verify:
|
|
|
|
- [ ] Message accurately describes the changes
|
|
- [ ] Type correctly categorizes the change
|
|
- [ ] Scope (if used) is meaningful and consistent
|
|
- [ ] Breaking changes are properly marked with `!` or footer
|
|
- [ ] Description is clear and under 50 characters
|
|
- [ ] Body wraps at 72 characters (if present)
|
|
|
|
## Examples
|
|
|
|
**Simple fix:**
|
|
```
|
|
fix: prevent null pointer in user lookup
|
|
```
|
|
|
|
**Feature with scope:**
|
|
```
|
|
feat(api): add rate limiting to endpoints
|
|
```
|
|
|
|
**With body:**
|
|
```
|
|
refactor: extract validation into separate module
|
|
|
|
Move validation logic from controllers to dedicated
|
|
validator classes for better testability and reuse.
|
|
```
|
|
|
|
**Breaking change:**
|
|
```
|
|
feat!: upgrade to v2 API format
|
|
|
|
BREAKING CHANGE: response structure changed from
|
|
{data: [...]} to {items: [...], meta: {...}}
|
|
```
|
|
|
|
**With issue reference:**
|
|
```
|
|
fix(auth): resolve token refresh race condition
|
|
|
|
Fixes #234
|
|
```
|
|
|
|
## Full Specification
|
|
|
|
For the complete Conventional Commits 1.0.0 specification including all rules and FAQ, see [references/full-spec.md](references/full-spec.md).
|