Initial commit
This commit is contained in:
Zhongwei Li
607
commands/commit-best-practices/workflow-tips.md
Normal file
607
commands/commit-best-practices/workflow-tips.md
Normal file
@@ -0,0 +1,607 @@
|
||||
# Operation: Git Workflow Tips and Best Practices
|
||||
|
||||
Comprehensive git workflow guidance covering commits, branches, merging, and collaboration.
|
||||
|
||||
## Parameters from $ARGUMENTS
|
||||
|
||||
- **focus** (optional): Specific area (commit|branch|merge|all) (default: all)
|
||||
|
||||
Parse as: `workflow-tips focus:commit` or `workflow-tips`
|
||||
|
||||
## Workflow Guidance
|
||||
|
||||
Route to specific section based on focus parameter:
|
||||
|
||||
### Focus: Commit Workflow
|
||||
|
||||
**Complete commit workflow best practices:**
|
||||
|
||||
```
|
||||
Git Commit Workflow Best Practices
|
||||
===================================
|
||||
|
||||
1. BEFORE YOU CODE
|
||||
------------------
|
||||
□ Create feature branch
|
||||
git checkout -b feature/your-feature-name
|
||||
|
||||
□ Pull latest changes
|
||||
git pull origin main
|
||||
|
||||
□ Verify clean state
|
||||
git status
|
||||
|
||||
|
||||
2. WHILE CODING
|
||||
---------------
|
||||
□ Commit frequently (atomic commits)
|
||||
- After each logical change
|
||||
- Not too small (typo fixes can be bundled)
|
||||
- Not too large (avoid 1000+ line commits)
|
||||
|
||||
□ Test before committing
|
||||
npm test (or your test command)
|
||||
|
||||
□ Keep commits focused
|
||||
- One concern per commit
|
||||
- Don't mix features and fixes
|
||||
- Don't mix multiple scopes
|
||||
|
||||
|
||||
3. BEFORE COMMITTING
|
||||
--------------------
|
||||
□ Review your changes
|
||||
git diff (see what changed)
|
||||
git status (see staged/unstaged)
|
||||
|
||||
□ Stage selectively
|
||||
git add <specific-files>
|
||||
(Don't blindly: git add .)
|
||||
|
||||
□ Run pre-commit checks
|
||||
/commit-best-practices check-pre-commit
|
||||
|
||||
□ Remove debug code
|
||||
- console.log, print statements
|
||||
- debugger statements
|
||||
- Temporary test code
|
||||
|
||||
|
||||
4. CREATING COMMIT
|
||||
------------------
|
||||
□ Use conventional commits format
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
□ Write clear subject (≤50 chars)
|
||||
- Imperative mood: "add" not "added"
|
||||
- Lowercase after type
|
||||
- No period at end
|
||||
|
||||
□ Add descriptive body (if needed)
|
||||
- Explain WHY, not what
|
||||
- Wrap at 72 characters
|
||||
- Use bullet points
|
||||
|
||||
□ Include footer (if applicable)
|
||||
- BREAKING CHANGE: description
|
||||
- Closes #123
|
||||
|
||||
|
||||
5. AFTER COMMITTING
|
||||
-------------------
|
||||
□ Review commit
|
||||
/commit-best-practices review-commit
|
||||
git show HEAD
|
||||
|
||||
□ Verify tests still pass
|
||||
npm test
|
||||
|
||||
□ Push to remote
|
||||
git push origin <branch>
|
||||
|
||||
□ Create pull request (if ready)
|
||||
gh pr create
|
||||
|
||||
|
||||
6. COMMON MISTAKES TO AVOID
|
||||
---------------------------
|
||||
❌ "WIP" or "work in progress" commits
|
||||
→ Finish work before committing
|
||||
|
||||
❌ "Fix" or "update" without context
|
||||
→ Be specific: "fix(auth): null pointer in OAuth"
|
||||
|
||||
❌ Committing all changes at once
|
||||
→ Split into atomic commits
|
||||
|
||||
❌ Forgetting to add tests
|
||||
→ Tests should accompany code changes
|
||||
|
||||
❌ Committing node_modules or .env files
|
||||
→ Use .gitignore properly
|
||||
|
||||
❌ Force pushing to shared branches
|
||||
→ Only force push on personal branches
|
||||
|
||||
|
||||
7. COMMIT CHECKLIST
|
||||
-------------------
|
||||
Before every commit, verify:
|
||||
|
||||
□ Changes are atomic (single logical change)
|
||||
□ Tests pass
|
||||
□ No debug code
|
||||
□ No TODOs in committed code
|
||||
□ Message follows conventions
|
||||
□ Includes tests (if new functionality)
|
||||
□ Documentation updated (if needed)
|
||||
|
||||
Use: /commit (agent handles checklist automatically)
|
||||
```
|
||||
|
||||
### Focus: Branch Workflow
|
||||
|
||||
**Branch management best practices:**
|
||||
|
||||
```
|
||||
Git Branch Workflow Best Practices
|
||||
===================================
|
||||
|
||||
1. BRANCH NAMING CONVENTIONS
|
||||
-----------------------------
|
||||
Follow consistent naming:
|
||||
|
||||
Feature branches:
|
||||
feature/oauth-authentication
|
||||
feature/user-profile-page
|
||||
|
||||
Bug fixes:
|
||||
fix/null-pointer-in-auth
|
||||
fix/memory-leak-in-parser
|
||||
|
||||
Hotfixes:
|
||||
hotfix/security-vulnerability
|
||||
hotfix/production-crash
|
||||
|
||||
Experiments:
|
||||
experiment/new-algorithm
|
||||
experiment/performance-optimization
|
||||
|
||||
Pattern: <type>/<brief-description>
|
||||
Use: lowercase-with-hyphens
|
||||
|
||||
|
||||
2. BRANCH LIFECYCLE
|
||||
-------------------
|
||||
Create → Develop → Test → Merge → Delete
|
||||
|
||||
Create:
|
||||
git checkout -b feature/my-feature
|
||||
(Always branch from main/develop)
|
||||
|
||||
Develop:
|
||||
- Commit frequently
|
||||
- Push regularly
|
||||
- Keep branch updated
|
||||
|
||||
Test:
|
||||
- Run full test suite
|
||||
- Manual testing
|
||||
- Code review
|
||||
|
||||
Merge:
|
||||
- Create pull request
|
||||
- Address review feedback
|
||||
- Merge to main
|
||||
|
||||
Delete:
|
||||
git branch -d feature/my-feature
|
||||
git push origin --delete feature/my-feature
|
||||
|
||||
|
||||
3. KEEPING BRANCHES UPDATED
|
||||
---------------------------
|
||||
Regularly sync with main branch:
|
||||
|
||||
Option 1: Rebase (cleaner history)
|
||||
git checkout feature/my-feature
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
Option 2: Merge (preserves history)
|
||||
git checkout feature/my-feature
|
||||
git merge origin/main
|
||||
|
||||
Recommendation: Use rebase for feature branches,
|
||||
merge for shared branches.
|
||||
|
||||
|
||||
4. BRANCH PROTECTION RULES
|
||||
---------------------------
|
||||
Protect important branches:
|
||||
|
||||
Main/Master:
|
||||
- Require pull request
|
||||
- Require code review
|
||||
- Require passing tests
|
||||
- Block force push
|
||||
- Block deletion
|
||||
|
||||
Develop:
|
||||
- Require pull request
|
||||
- Require passing tests
|
||||
- Allow force push with lease
|
||||
|
||||
Feature:
|
||||
- No restrictions
|
||||
- Personal branches
|
||||
|
||||
|
||||
5. LONG-RUNNING BRANCHES
|
||||
-------------------------
|
||||
If branch lives more than a few days:
|
||||
|
||||
□ Sync with main frequently (daily)
|
||||
□ Keep commits atomic and clean
|
||||
□ Push to remote regularly
|
||||
□ Communicate with team
|
||||
□ Consider splitting into smaller branches
|
||||
|
||||
|
||||
6. BRANCH STRATEGIES
|
||||
--------------------
|
||||
Choose strategy based on team size:
|
||||
|
||||
Git Flow (large teams):
|
||||
- main: production
|
||||
- develop: integration
|
||||
- feature/*: new features
|
||||
- release/*: release prep
|
||||
- hotfix/*: urgent fixes
|
||||
|
||||
GitHub Flow (small teams):
|
||||
- main: production
|
||||
- feature/*: all work
|
||||
(Simple and effective)
|
||||
|
||||
Trunk-Based (continuous deployment):
|
||||
- main: always deployable
|
||||
- Short-lived feature branches
|
||||
- Feature flags for incomplete work
|
||||
|
||||
|
||||
7. COMMON BRANCH MISTAKES
|
||||
--------------------------
|
||||
❌ Working directly on main
|
||||
→ Always use feature branches
|
||||
|
||||
❌ Branches that live for weeks
|
||||
→ Split into smaller branches
|
||||
|
||||
❌ Not syncing with main regularly
|
||||
→ Causes massive merge conflicts
|
||||
|
||||
❌ Unclear branch names (branch1, temp)
|
||||
→ Use descriptive names
|
||||
|
||||
❌ Leaving merged branches
|
||||
→ Delete after merging
|
||||
|
||||
❌ Force pushing shared branches
|
||||
→ Only force push personal branches
|
||||
```
|
||||
|
||||
### Focus: Merge Workflow
|
||||
|
||||
**Merge and pull request best practices:**
|
||||
|
||||
```
|
||||
Git Merge Workflow Best Practices
|
||||
==================================
|
||||
|
||||
1. BEFORE CREATING PULL REQUEST
|
||||
-------------------------------
|
||||
□ All commits are atomic
|
||||
/commit-review (check quality)
|
||||
|
||||
□ Branch is up-to-date
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
□ All tests pass
|
||||
npm test (full suite)
|
||||
|
||||
□ No merge conflicts
|
||||
Resolve before creating PR
|
||||
|
||||
□ Code is reviewed locally
|
||||
Self-review your changes
|
||||
|
||||
|
||||
2. CREATING PULL REQUEST
|
||||
------------------------
|
||||
Good PR title:
|
||||
feat(auth): Add OAuth authentication support
|
||||
|
||||
Good PR description:
|
||||
## Summary
|
||||
Implements OAuth 2.0 authentication for Google and GitHub.
|
||||
|
||||
## Changes
|
||||
- OAuth configuration system
|
||||
- Provider implementations (Google, GitHub)
|
||||
- Token refresh mechanism
|
||||
- Middleware integration
|
||||
|
||||
## Testing
|
||||
- Unit tests: 15 added
|
||||
- Integration tests: 3 added
|
||||
- Manual testing: OAuth flows verified
|
||||
|
||||
## Screenshots (if UI)
|
||||
[Include screenshots]
|
||||
|
||||
Closes #123
|
||||
|
||||
|
||||
3. CODE REVIEW PROCESS
|
||||
----------------------
|
||||
As author:
|
||||
□ Respond to all comments
|
||||
□ Make requested changes
|
||||
□ Push new commits (don't amend!)
|
||||
□ Re-request review when ready
|
||||
□ Be open to feedback
|
||||
|
||||
As reviewer:
|
||||
□ Review code thoroughly
|
||||
□ Check tests are included
|
||||
□ Verify documentation updated
|
||||
□ Test locally if possible
|
||||
□ Be constructive in feedback
|
||||
|
||||
|
||||
4. MERGE STRATEGIES
|
||||
-------------------
|
||||
Choose appropriate merge strategy:
|
||||
|
||||
Merge Commit (default):
|
||||
git merge --no-ff feature/my-feature
|
||||
- Preserves complete history
|
||||
- Shows where feature was merged
|
||||
- Creates merge commit
|
||||
Use for: Significant features
|
||||
|
||||
Squash Merge:
|
||||
git merge --squash feature/my-feature
|
||||
- Combines all commits into one
|
||||
- Clean linear history
|
||||
- Loses individual commit detail
|
||||
Use for: Small features, many WIP commits
|
||||
|
||||
Rebase Merge:
|
||||
git rebase main
|
||||
git merge --ff-only
|
||||
- Linear history
|
||||
- No merge commit
|
||||
- Clean git log
|
||||
Use for: Personal branches, small changes
|
||||
|
||||
|
||||
5. RESOLVING MERGE CONFLICTS
|
||||
-----------------------------
|
||||
When conflicts occur:
|
||||
|
||||
Step 1: Identify conflicts
|
||||
git status (shows conflicted files)
|
||||
|
||||
Step 2: Open conflicted file
|
||||
Conflict markers:
|
||||
<<<<<<< HEAD
|
||||
Your changes
|
||||
=======
|
||||
Their changes
|
||||
>>>>>>> feature/branch
|
||||
|
||||
Step 3: Resolve conflict
|
||||
- Choose one version, or
|
||||
- Combine both versions, or
|
||||
- Write new solution
|
||||
|
||||
Step 4: Remove conflict markers
|
||||
Delete <<<<<<<, =======, >>>>>>>
|
||||
|
||||
Step 5: Mark as resolved
|
||||
git add <resolved-file>
|
||||
|
||||
Step 6: Complete merge
|
||||
git merge --continue
|
||||
(or git rebase --continue)
|
||||
|
||||
Step 7: Test thoroughly
|
||||
npm test
|
||||
Manual testing
|
||||
|
||||
|
||||
6. AFTER MERGING
|
||||
----------------
|
||||
□ Delete feature branch
|
||||
git branch -d feature/my-feature
|
||||
git push origin --delete feature/my-feature
|
||||
|
||||
□ Verify merge on main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git log (verify commit appears)
|
||||
|
||||
□ Run tests on main
|
||||
npm test
|
||||
|
||||
□ Deploy if applicable
|
||||
(Follow deployment process)
|
||||
|
||||
□ Update issue tracker
|
||||
Close related issues
|
||||
|
||||
□ Notify stakeholders
|
||||
Team notification of merge
|
||||
|
||||
|
||||
7. MERGE BEST PRACTICES
|
||||
------------------------
|
||||
✅ Merge frequently (avoid long-lived branches)
|
||||
✅ Require code review before merge
|
||||
✅ Ensure tests pass before merge
|
||||
✅ Delete branches after merge
|
||||
✅ Use meaningful merge commit messages
|
||||
✅ Squash "fix review comments" commits
|
||||
|
||||
❌ Don't merge failing tests
|
||||
❌ Don't merge without review
|
||||
❌ Don't merge with unresolved conflicts
|
||||
❌ Don't merge incomplete features to main
|
||||
❌ Don't forget to pull after merge
|
||||
```
|
||||
|
||||
### Focus: All (Complete Workflow)
|
||||
|
||||
When `focus:all` or no focus specified, provide comprehensive overview:
|
||||
|
||||
```
|
||||
Complete Git Workflow Guide
|
||||
============================
|
||||
|
||||
Quick Reference for Git Best Practices
|
||||
|
||||
DAILY WORKFLOW
|
||||
--------------
|
||||
1. Start day: git pull origin main
|
||||
2. Create branch: git checkout -b feature/name
|
||||
3. Code & commit frequently (atomic commits)
|
||||
4. Test before each commit
|
||||
5. Push regularly: git push origin feature/name
|
||||
6. Create PR when ready
|
||||
7. Address review feedback
|
||||
8. Merge and delete branch
|
||||
9. Pull updated main
|
||||
|
||||
COMMIT GUIDELINES
|
||||
-----------------
|
||||
Format: <type>(<scope>): <subject>
|
||||
|
||||
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
|
||||
|
||||
Subject: ≤50 chars, imperative, lowercase, no period
|
||||
Body: Wrap at 72 chars, explain WHY
|
||||
Footer: BREAKING CHANGE, Closes #123
|
||||
|
||||
BRANCH STRATEGY
|
||||
---------------
|
||||
- main: production-ready code
|
||||
- feature/*: new features
|
||||
- fix/*: bug fixes
|
||||
- hotfix/*: urgent production fixes
|
||||
|
||||
Keep branches short-lived (< 1 week)
|
||||
Sync with main daily
|
||||
Delete after merging
|
||||
|
||||
MERGE PROCESS
|
||||
-------------
|
||||
1. Rebase on main: git rebase origin/main
|
||||
2. Resolve conflicts
|
||||
3. All tests pass
|
||||
4. Code review approved
|
||||
5. Merge to main
|
||||
6. Delete feature branch
|
||||
|
||||
TOOLS TO USE
|
||||
------------
|
||||
/commit - Create commit with agent assistance
|
||||
/commit-review - Review commit quality
|
||||
/commit-split - Split non-atomic commits
|
||||
/commit-best-practices check-pre-commit - Validate before commit
|
||||
/commit-best-practices review-commit - Review commit after creation
|
||||
/commit-best-practices amend-guidance - Safe amend help
|
||||
/commit-best-practices revert-guidance - Revert help
|
||||
|
||||
COMMON COMMANDS
|
||||
---------------
|
||||
git status # Check status
|
||||
git diff # See changes
|
||||
git add <files> # Stage changes
|
||||
git commit # Create commit
|
||||
git push origin <branch> # Push to remote
|
||||
git pull origin main # Get latest main
|
||||
git log --oneline -10 # Recent commits
|
||||
git show HEAD # Show last commit
|
||||
|
||||
EMERGENCY PROCEDURES
|
||||
--------------------
|
||||
Committed to wrong branch:
|
||||
git reset --soft HEAD~1
|
||||
git checkout correct-branch
|
||||
git commit
|
||||
|
||||
Pushed wrong commit:
|
||||
git revert HEAD
|
||||
git push
|
||||
|
||||
Need to undo local changes:
|
||||
git checkout -- <file>
|
||||
(or git restore <file>)
|
||||
|
||||
Accidentally deleted branch:
|
||||
git reflog
|
||||
git checkout -b branch-name <sha>
|
||||
|
||||
For more detailed guidance on specific areas:
|
||||
/commit-best-practices workflow-tips focus:commit
|
||||
/commit-best-practices workflow-tips focus:branch
|
||||
/commit-best-practices workflow-tips focus:merge
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
Provide guidance formatted with:
|
||||
- Clear section headers
|
||||
- Checkboxes for actionable items
|
||||
- Code examples with syntax highlighting
|
||||
- Visual indicators (✅ ❌ ⚠️)
|
||||
- Step-by-step instructions
|
||||
- Common pitfalls and solutions
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Invalid focus parameter:**
|
||||
```
|
||||
ERROR: Invalid focus: invalid-focus
|
||||
Valid options: commit, branch, merge, all
|
||||
Example: /commit-best-practices workflow-tips focus:commit
|
||||
```
|
||||
|
||||
## Integration with Agent
|
||||
|
||||
Proactively suggest workflow tips when:
|
||||
- User commits to main branch directly (suggest feature branch)
|
||||
- Branch hasn't been synced in 3+ days (suggest rebase)
|
||||
- PR has many commits (suggest squash)
|
||||
- User attempts unsafe operation (provide guidance)
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
**The Golden Rules:**
|
||||
|
||||
1. **Commit often** - Atomic, focused commits
|
||||
2. **Test always** - Before every commit
|
||||
3. **Branch per feature** - Isolate work
|
||||
4. **Sync regularly** - Stay updated with main
|
||||
5. **Review thoroughly** - All code reviewed
|
||||
6. **Merge cleanly** - No conflicts, passing tests
|
||||
7. **Delete branches** - After merging
|
||||
8. **Communicate** - Keep team informed
|
||||
|
||||
**Tools make it easier:**
|
||||
Use `/commit` and related skills to automate best practices and ensure consistent, high-quality commits.
|
||||
|
||||
These workflows ensure clean history, facilitate collaboration, and make debugging easier when issues arise.
|
||||
Reference in New Issue
Block a user