mev-beta/docs/5_development/GIT_WORKFLOW.md

# Git Workflow for MEV Bot Project

This document outlines the Git workflow, best practices, and configurations for the MEV Bot project.

## 🌿 Branch Strategy

### Branch Naming Conventions
```
main                    # Production-ready code
develop                 # Main development branch
feature/<description>   # New features (e.g., feature/add-market-scanner)
fix/<description>       # Bug fixes (e.g., fix/memory-leak)
hotfix/<description>    # Critical production fixes (e.g., hotfix/security-patch)
release/<version>       # Release preparation (e.g., release/v1.2.0)
```

### Branch Hierarchy
```
main
└── develop
    ├── feature/add-market-scanner
    ├── feature/improve-performance
    ├── fix/resolve-race-condition
    └── release/v1.2.0
```

## 📝 Commit Message Conventions

### Format
```
type(scope): brief description

- Detailed explanation of changes
- Why the change was needed
- Any breaking changes or migration notes

Resolves: #123
See also: #456
```

### Types
- `feat`: New feature implementation
- `fix`: Bug fix
- `perf`: Performance improvement
- `refactor`: Code restructuring without feature changes
- `test`: Adding or updating tests
- `docs`: Documentation updates
- `build`: Build system or dependency changes
- `ci`: CI/CD pipeline changes
- `chore`: Maintenance tasks

### Scopes
- `arbitrum`: Arbitrum monitoring components
- `market`: Market analysis and scanning
- `uniswap`: Uniswap V3 pricing functions
- `config`: Configuration management
- `security`: Security-related changes
- `performance`: Performance optimizations
- `testing`: Test-related changes
- `logging`: Logging improvements
- `monitor`: Monitoring components
- `scanner`: Market scanning components

## 🔄 Workflow Process

### 1. Feature Development
```bash
# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/new-feature-name

# Make changes and commit frequently
git add .
git commit -m "feat(scope): description of changes"

# Push branch to remote
git push -u origin feature/new-feature-name
```

### 2. Code Review Process
1. Create Pull Request from feature branch to develop
2. Request review from team members
3. Address feedback and make changes
4. Get approval from reviewers
5. Merge to develop

### 3. Release Process
```bash
# Create release branch
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# Finalize release (version bumps, docs, etc.)
git add .
git commit -m "chore(release): prepare v1.2.0"

# Merge to main and develop
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

git checkout develop
git merge release/v1.2.0
git push origin develop

# Delete release branch
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0
```

### 4. Hotfix Process
```bash
# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-bug

# Fix bug and commit
git add .
git commit -m "fix(security): resolve critical vulnerability"

# Merge to main and develop
git checkout main
git merge hotfix/critical-bug
git tag -a v1.1.1 -m "Hotfix v1.1.1"
git push origin main --tags

git checkout develop
git merge hotfix/critical-bug
git push origin develop

# Delete hotfix branch
git branch -d hotfix/critical-bug
git push origin --delete hotfix/critical-bug
```

## 🛡️ Git Hooks

### Pre-commit Hook
Validates code quality before committing:
- Run linters
- Run tests
- Check for secrets
- Validate commit message format

### Pre-push Hook
Validates code before pushing:
- Run full test suite
- Run security scans
- Check code coverage

## 📊 Git Configuration

### User Configuration
```bash
git config user.name "Your Name"
git config user.email "your.email@example.com"
```

### Project Configuration
```bash
# Enable color output
git config color.ui auto

# Set default editor
git config core.editor "code --wait"

# Enable rebasing when pulling
git config pull.rebase true

# Set up push behavior
git config push.default simple

# Enable Git Large File Storage (if needed)
git config lfs.repositoryformatversion 0
```

## 🔧 Git Aliases

Add these helpful aliases to your Git configuration:
```bash
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'
git config --global alias.graph 'log --oneline --graph --decorate --all'
git config --global alias.amend 'commit --amend'
git config --global alias.fixup 'commit --fixup'
```

## 🚀 Best Practices

### Commit Frequency
- Commit early and often
- Each commit should represent a single logical change
- Write clear, descriptive commit messages
- Keep commits small and focused

### Branch Management
- Delete branches after merging
- Keep feature branches up to date with develop
- Use descriptive branch names
- Limit branch lifetime (max 1-2 weeks)

### Merge Strategies
- Use merge commits for feature branches to preserve history
- Use rebase for cleaning up local commit history
- Use squash merge for small features with multiple commits
- Always review changes before merging

### Code Review
- Review code before merging to develop or main
- Ensure tests pass and coverage is maintained
- Check for security vulnerabilities
- Verify code follows project standards

## 📈 Git Workflow Metrics

Track these metrics to improve the development process:
- Average time from feature branch to merge
- Number of commits per pull request
- Code review turnaround time
- Merge conflict frequency
- Release frequency

## 🆘 Troubleshooting

### Common Issues

#### Merge Conflicts
```bash
# Resolve conflicts and continue merge
git add .
git commit

# Abort merge if needed
git merge --abort
```

#### Accidental Commits
```bash
# Amend last commit
git commit --amend

# Remove file from last commit
git reset --soft HEAD~1
```

#### Lost Commits
```bash
# Find lost commits
git reflog

# Restore to specific commit
git reset --hard HEAD@{n}
```

This Git workflow ensures consistent, high-quality code contributions while maintaining a clean, traceable history.