majiayu000 When to Use
- User asks to create a commit or "commit changes"
- User asks to review git status or diff
- User wants to analyze commit history
- After completing features/fixes that need to be committed
- User mentions "conventional commits" or asks about commit format
Critical Patterns
Commit Format
<type>(<scope>): <subject>
[optional body]
[optional footer]
Types (in order of usage frequency)
| Type | Description | Example |
|---|---|---|
feat |
New functionality | feat(library/book): add ISBN validation |
fix |
Bug fix | fix(auth): resolve token refresh race condition |
refactor |
Code refactoring, no functional change | refactor(core): extract validation logic to service |
test |
Add or modify tests | test(book): add unit tests for create handler |
docs |
Documentation changes | docs(readme): add installation instructions |
chore |
Maintenance tasks | chore(deps): update nestjs to v10 |
style |
Formatting, semicolons, etc. | style(api): apply prettier formatting |
perf |
Performance improvements | perf(query): optimize book search with index |
ci |
CI/CD changes | ci(github): add deployment workflow |
build |
Build system or dependencies | build(docker): optimize production image |
revert |
Revert previous commit | revert: feat(book): add ISBN validation |
Subject Rules
- ✅ Use imperative mood: "add" NOT "added" or "adds"
- ✅ Lowercase first letter
- ✅ No period at the end
- ✅ Maximum 120 characters
- ✅ Describe WHAT, not HOW
Good:
feat(book): add publication date validationfix(auth): resolve token refresh issue
Bad:
feat(book): Added publication date validation(past tense)fix(auth): Resolve token refresh issue(uppercase)feat(book): add publication date validation.(period)
Body Rules (Optional)
- Separate from subject with blank line
- Explain WHY, not WHAT
- Wrap at 72 characters per line
- Can use bullet points with
-
Footer Rules (Optional)
- Reference issues:
Closes #123,Fixes #456 - Breaking changes:
BREAKING CHANGE: <description> - ❌ NEVER add "Co-Authored-By" or AI attribution
Commit Workflow
1. Analyze Changes
git status # See modified/untracked files
git diff # See unstaged changes
git diff --staged # See staged changes
git log --oneline -10 # See recent commit style
2. Group Related Changes
Rules:
- One commit = one logical change
- ❌ Don't mix features with fixes
- ❌ Don't mix multiple unrelated modules
- ✅ Multiple files are OK if they implement one feature
3. Generate Message
Analyze the changes and determine:
- Type: feat, fix, refactor, etc.
- Scope: Which module/component is affected?
- Subject: What does this change do?
- Body (if needed): Why was this change necessary?
- Footer (if needed): Issue references, breaking changes
4. Execute Commit
git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>
<body>
<footer>
EOF
)"
Code Examples
Simple Feature
feat(library/book): add publication date validation
Validate that publication date is not in the future
when creating or updating a book.
Closes #234
Bug Fix with Context
fix(auth): resolve token refresh race condition
Multiple simultaneous requests could trigger parallel
token refreshes, causing some requests to fail.
- Add mutex lock during refresh
- Queue pending requests until refresh completes
- Add retry logic for failed requests
Fixes #567
Refactor (No Functional Change)
refactor(library/book): extract ISBN validation to service
Move ISBN validation logic from command handler to
dedicated IsbnValidatorService for reusability.
No functional changes.
Breaking Change
feat(api)!: change pagination response format
BREAKING CHANGE: Pagination response now uses cursor-based
format instead of offset-based.
Before: { items: [], total: 100, page: 1 }
After: { items: [], nextCursor: "abc", hasMore: true }
Migration guide in docs/migration/v2-pagination.md
Aurora YAML Changes
feat(aurora): add category entity to library module
Define new Category aggregate with:
- id, name, description fields
- many-to-many relation with Book
Run: aurora load back module -n=library/category
Dependency Update
chore(deps): update @nestjs packages to v10.2.0
- @nestjs/core: 10.1.0 -> 10.2.0
- @nestjs/common: 10.1.0 -> 10.2.0
- @nestjs/platform-express: 10.1.0 -> 10.2.0
No breaking changes in this update.
Multiple Modules (Related Change)
feat(tesla): add maintenance validation across models
- Add validation in Model aggregate
- Update MaintenanceHistory to check model status
- Add integration tests for both modules
This ensures consistency when creating maintenance records.
Commands
# View status
git status
# View changes
git diff # Unstaged changes
git diff --staged # Staged changes
git diff --cached # Same as --staged
# Stage files
git add <file> # Stage specific file
git add -p # Interactive staging (choose hunks)
# Commit
git commit -m "message" # Simple commit
git commit # Opens editor for body
# View history
git log --oneline -20 # Last 20 commits
git log --pretty=format:"%h %s" -20 # Custom format
git log --graph --oneline --all # Visual graph
# Amend last commit (use with caution)
git commit --amend -m "new message" # Change message
git commit --amend --no-edit # Add files to last commit
Anti-Patterns to Avoid
| ❌ Bad | ✅ Good |
|---|---|
git commit -m "fix" |
fix(auth): resolve token expiration bug |
git commit -m "WIP" |
Finish the work or use feature branch |
git commit -m "changes" |
refactor(core): extract common validation logic |
git commit -m "update files" |
feat(book): add ISBN field to entity |
git commit -am "everything" |
Split into logical commits |
| Mix feat + fix + refactor | Separate commits for each type |
| Commit generated files only | Commit YAML changes + explain regeneration |
Aurora-Specific Notes
1. YAML Changes
feat(aurora): add category entity to library module
Define new Category aggregate with id, name, description.
Run: aurora load back module -n=library/category
2. Custom Logic in Generated Files
feat(library/book): add complex ISBN validation logic
Implement custom validation in CreateBookHandler:
- Validate ISBN format (10 or 13 digits)
- Check checksum digit
- Verify not in blacklist
This logic is in a generated file marked as custom.
3. Multiple Related Modules
feat(tesla): integrate maintenance history with models
- Update Model aggregate with maintenance status
- Add validation in MaintenanceHistory creation
- Add integration tests
Changes span tesla/model and tesla/maintenance-history.
4. Test Commits
Option A: Combined with feature
feat(book): add ISBN validation with tests
- Add ISBN validation in CreateBookHandler
- Add unit tests for validation logic
- Add e2e tests for create endpoint
Option B: Separate commit
test(book): add unit tests for ISBN validation
Add comprehensive test coverage for:
- Valid ISBN-10 and ISBN-13 formats
- Invalid formats and checksums
- Edge cases (empty, null, special chars)
Decision Trees
Should I commit now?
Has code changed? ────NO───> No commit needed
│
YES
│
Is it a logical unit? ────NO───> Break into smaller commits
│
YES
│
Do tests pass? ────NO───> Fix tests first
│
YES
│
Create commit
What type should I use?
New functionality? ────YES───> feat
│
NO
│
Fixing a bug? ────YES───> fix
│
NO
│
No functional change? ────YES───> refactor
│
NO
│
Only tests? ────YES───> test
│
NO
│
Dependencies? ────YES───> chore(deps)
│
NO
│
Documentation? ────YES───> docs
│
NO
│
Default: chore
How to scope?
Single module changed? ────YES───> Use <bc>/<module>
│
NO
│
Multiple related modules? ────YES───> Use common <bc> or higher scope
│
NO
│
Infrastructure? ────YES───> Use: ci, docker, config, deps
│
NO
│
Core/API/GraphQL? ────YES───> Use: core, api, graphql
│
NO
│
Omit scope or use project name
Related Skills
This skill works with:
- aurora-cli: Commit YAML changes and regenerated code
- aurora-development: Commit business logic implementations (feat commits)
- jest-nestjs: Commit test files (test commits or include with feat)
- logger: Log commit information in session reports
Workflow:
- Make changes (YAML modifications, business logic, tests)
- Use aurora-cli to regenerate code (if YAML changed)
- Use conventional-commits to create proper commit
- Use logger to document the session (optional)
Resources
- Specification: https://www.conventionalcommits.org/
- Aurora Config:
commitlint.config.js(read this for project-specific rules) - Git Hooks: Pre-commit hooks may enforce format validation