KwokYC Smart Commit
Generate clear, conventional commit messages and PR descriptions from actual code changes.
Commit Message Format
Follow Conventional Commits:
<type>(<scope>): <subject>
<body>
<footer>
Types
| Type | When to use |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
refactor |
Code change that neither fixes a bug nor adds a feature |
perf |
Performance improvement |
test |
Adding or updating tests |
chore |
Build process, CI, dependencies |
style |
Formatting, whitespace (no code change) |
ci |
CI/CD configuration |
revert |
Reverting a previous commit |
Subject Rules
✅ feat(auth): add JWT refresh token support
✅ fix(api): handle null response in user endpoint
✅ refactor(db): extract connection pooling logic
❌ feat: update stuff
❌ fix: fixed bug
❌ WIP
❌ .
Rules:
- Use imperative mood: "add" not "added", "fix" not "fixed"
- Lowercase first letter
- No period at the end
- Max 72 characters
- Describe WHAT, not HOW
Body (when needed)
feat(payments): add Stripe webhook handler
Add endpoint to handle Stripe payment_intent.succeeded events.
Updates order status and sends confirmation email on success.
Previously we only polled for payment status, which caused
delays of up to 30 seconds for order confirmation.
Rules:
- Wrap at 72 characters
- Explain WHY, not WHAT (the diff shows WHAT)
- Separate from subject with blank line
- Use present tense
Footer
Fixes #123
Closes #456
BREAKING CHANGE: removed legacy API endpoint /v1/users
Co-authored-by: Name <email@example.com>
How to Generate a Commit Message
1. Run: git diff --staged
2. Analyze what changed and why
3. Determine type (feat/fix/refactor/etc.)
4. Identify scope from file paths
5. Write subject: type(scope): what changed
6. Write body if change is non-trivial
7. Reference issue if applicable
Scope Detection
Files in src/auth/ → scope: auth
Files in src/api/users → scope: users or api
Files in tests/ → scope: test (or match the feature scope)
Files in docs/ → docs type
package.json changes → chore type, no scope or deps scope
CI files → ci type
Multi-File Commit Strategy
When changes span multiple concerns:
❌ Single commit: "update user module" (touches auth, API, DB, tests, docs)
✅ Split into:
1. feat(db): add refresh_token column to users table
2. feat(auth): implement JWT refresh token logic
3. feat(api): add POST /auth/refresh endpoint
4. test(auth): add refresh token tests
5. docs(api): document refresh token endpoint
PR Description Template
## What
Brief description of what this PR does.
## Why
Why this change is needed. Link to issue or context.
## How
Key implementation decisions. Not line-by-line, but notable choices.
## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing done (describe what)
- [ ] Edge cases considered
## Screenshots (if UI changes)
[Before] → [After]
PR Description Rules
✅ PR Description:
## What
Add user avatar upload with S3 storage.
## Why
Users currently can't customize their profile. Issue #234.
## How
- Added presigned URL generation for S3 uploads
- Image resizing via Sharp on upload
- Max file size: 5MB, formats: jpg/png/webp
## Testing
- Unit tests for upload validation
- Integration test with S3 mock
- Manually tested with 10MB file (rejected), 4MB file (accepted)
❌ PR Description:
"updated user profile"
"fixes"
"changes"
Commit Workflow
1. Stage specific files (not git add .)
git add src/auth/jwt.ts src/auth/jwt.test.ts
2. Review what you're staging
git diff --staged
3. Generate message based on actual changes
- What files changed?
- What's the net effect?
- What type of change?
4. Write commit
git commit -m "$(cat <<'EOF'
feat(auth): add JWT refresh token logic
Implement automatic token refresh when access token expires.
Uses sliding window expiration with 7-day max lifetime.
EOF
)"
Handling Special Cases
Squash Commits
When merging PR, squash to one meaningful commit:
feat(payments): add Stripe integration (#123)
Revert
revert: feat(auth): add SSO login support
This reverts commit abc123.
Reason: SSO provider has outage, reverting until resolved.
WIP / Draft
Only in local branches, never in main/develop:
wip: exploring payment webhook approach
Squash before merge into meaningful commits.
Quick Reference
# See staged changes
git diff --staged
# See recent commits for style reference
git log --oneline -10
# Amend last commit message (before push)
git commit --amend -m "better message"
# Interactive rebase to clean up commits
git rebase -i main