Git Workflow Guide

Git Workflow Guide

Complete Git workflow standards for professional development with integrated TDD and code review.

Quick Reference

Commit Message Format

<type>: <description>

<optional body>

Types

• feat: New feature
• fix: Bug fix
• refactor: Code refactoring (no functionality change)
• docs: Documentation updates
• test: Test-related changes
• chore: Build process or auxiliary tool changes
• perf: Performance optimization
• ci: CI/CD configuration changes

Examples

# Good commit messages
feat: add user authentication feature
fix: resolve sidebar display issue
refactor: restructure API response handling logic
docs: update README installation instructions

# Bad commit messages
update code
fix bug
changes

Rules

• Use present tense: "add feature" not "added feature"
• Lowercase first letter
• No period at the end
• Keep description concise (≤50 characters)
• Body is optional for detailed explanation

Pull Request Workflow

Pre-PR Checklist

1. Analyze Complete Commit History

   git log --oneline
   

2. Review All Changes

   git diff main...HEAD
   git diff --stat main...HEAD
   

3. Ensure Tests Pass

   npm run test
   npm run build
   npm run lint
   

PR Creation Steps

1. Push Branch (use -u flag for new branches)

   git push -u origin feature/your-feature-name
   

2. Write Detailed PR Summary

   • Explain purpose and background of changes
   • List main change points
   • Include related issue links

3. Include Test Plan

   ## Test Plan
   - [ ] Unit tests pass
   - [ ] Integration tests pass
   - [ ] Manual testing complete
   - [ ] Browser compatibility tested
   

4. Add TODOs (if any)

   ## TODOs
   - [ ] Add more edge case tests
   - [ ] Update related documentation
   - [ ] Performance optimization
   

PR Review Standards

Follow Code Quality Power's code-review.md for systematic review:

• Security check (CRITICAL)
• Logic correctness (HIGH)
• Error handling (HIGH)
• Test coverage (HIGH)
• Code quality (MEDIUM)

Feature Implementation Workflow

1. Plan First

Use Development Workflow Power's planner

Steps:
1. Read planner.md steering file
2. Create implementation plan
3. Identify dependencies and risks
4. Break down into multiple phases

Output: Detailed implementation plan document

2. TDD Methodology

Use Development Workflow Power's tdd-guide

TDD Cycle:
1. Write test (RED) - Test should fail
2. Implement feature (GREEN) - Make test pass
3. Refactor (REFACTOR) - Improve code quality
4. Verify coverage (VERIFY) - Ensure 80%+ coverage

Reference: See testing standards in testing steering

3. Code Review

Use Code Quality Power's code-reviewer

Review Timing:
- Immediately after writing code
- Before submitting PR
- Before merging to main branch

Priority Handling:

• CRITICAL issues: Must fix
• HIGH issues: Should fix
• MEDIUM issues: Consider fixing
• LOW issues: Optional fix

4. Commit and Push

Follow conventional commit format

# 1. Stage changes
git add .

# 2. Commit (use standard format)
git commit -m "feat: add user authentication feature"

# 3. Push to remote
git push origin feature/user-auth

Branch Management Strategy

Branch Naming Convention

feature/feature-name    - New feature development
fix/issue-description   - Bug fix
refactor/refactor-content - Code refactoring
docs/documentation-update - Documentation changes
test/test-content       - Test-related

Examples

feature/user-authentication
fix/sidebar-display-issue
refactor/api-response-handler
docs/update-readme
test/add-unit-tests

Branch Lifecycle

1. Create Branch

   git checkout -b feature/new-feature
   

2. Regularly Sync Main Branch

   git fetch origin
   git rebase origin/main
   

3. Delete After Merge

   git branch -d feature/new-feature
   git push origin --delete feature/new-feature
   

Code Review Checklist

Before submitting PR, self-review:

Functionality

• Feature works as expected
• Edge cases handled
• Error handling implemented

Code Quality

• Code is clear and readable
• Follows project coding standards
• No duplicate code
• Functions and variables clearly named

Testing

• Unit tests added
• Test coverage ≥ 80%
• All tests pass
• Edge cases tested

Documentation

• Code comments are clear
• README updated (if needed)
• API documentation updated (if needed)
• CHANGELOG updated

Security

• No hardcoded keys or passwords
• Input validation implemented
• No SQL injection risk
• No XSS vulnerabilities

Common Git Commands

View Status and History

# View current status
git status

# View commit history
git log --oneline --graph --all

# View specific file history
git log --follow -- path/to/file

# View change statistics
git diff --stat

Undo and Modify

# Undo working directory changes
git checkout -- file.txt

# Unstage file
git reset HEAD file.txt

# Modify last commit
git commit --amend

# Undo last commit (keep changes)
git reset --soft HEAD~1

Branch Operations

# View all branches
git branch -a

# Switch branch
git checkout branch-name

# Create and switch to new branch
git checkout -b new-branch

# Delete local branch
git branch -d branch-name

# Delete remote branch
git push origin --delete branch-name

Common Issues and Solutions

Issue 1: Wrong Commit Message

# Modify last commit message
git commit --amend -m "correct commit message"

# If already pushed, need force push (use cautiously)
git push --force-with-lease

Issue 2: Forgot to Switch Branch

# Stash current work
git stash

# Switch to correct branch
git checkout correct-branch

# Restore work
git stash pop

Issue 3: Need to Combine Multiple Commits

# Interactive rebase (combine last 3 commits)
git rebase -i HEAD~3

# In editor, mark commits to squash
# Save and exit, then edit combined commit message

Issue 4: Conflict Resolution

# 1. Pull latest code
git fetch origin
git rebase origin/main

# 2. Resolve conflicts (edit conflict files)

# 3. Mark as resolved
git add .

# 4. Continue rebase
git rebase --continue

# If need to abort rebase
git rebase --abort

Integration with Development Workflow

Align Phase

• Create feature branch
• Document requirements in ALIGNMENT.md

Architect Phase

• Design documented in DESIGN.md
• Commit design decisions

Atomize Phase

• Break into tasks in TASK.md
• Each task = separate commit

Automate Phase

• Follow TDD for each task
• Commit after each task completion
• Use conventional commit format

Assess Phase

• Create PR with complete summary
• Request code review
• Address review feedback
• Merge after approval

Best Practices Summary

1. Frequent Commits - Small steps, each commit does one thing
2. Clear Messages - Let others (and future you) quickly understand changes
3. Timely Sync - Regularly pull from main branch, avoid large conflicts
4. Code Review - Self-review before submitting, request others' review after
5. Test First - Follow TDD, ensure code quality
6. Sync Documentation - Update documentation when code changes

Related Documentation

• Testing Standards: See testing steering
• Code Review: See code-quality power's code-review.md
• Development Workflow: See development-workflow power
• Coding Standards: See coding steering

Remember: Good Git workflow is the foundation of team collaboration. Clear commits and systematic reviews make everyone's life easier.