mev-beta/docs/BRANCH_STRUCTURE.md

# V2 Branch Structure

## Overview

The MEV Bot V2 project uses a structured branching strategy to maintain code quality, enable parallel development, and ensure production stability.

## Branch Hierarchy

```
v2-master (production)
  ↑
  └── v2-master-dev (development)
        ↑
        ├── feature/v2/parsers/*
        ├── feature/v2/arbitrage/*
        ├── feature/v2/execution/*
        └── feature/v2/*
```

---

## Branch Descriptions

### 🔒 `v2-master` (Production Branch)

**Purpose:** Production-ready code only
**Protection:** Protected, requires PR approval
**Updates:** Only from `v2-master-dev` via merge
**CI/CD:** Full pipeline on every push

**Status:**
- ✅ Foundation complete (100% coverage)
- ✅ CI/CD configured
- ✅ Documentation complete
- ✅ Ready for production deployment

**Rules:**
- ❌ NEVER commit directly to v2-master
- ✅ Only merge from v2-master-dev
- ✅ Must pass all CI/CD checks
- ✅ Requires code review approval
- ✅ Must maintain 100% test coverage

**When to merge:**
- After thorough testing in v2-master-dev
- When ready for production deployment
- After all features in a release are complete
- When stability is confirmed

### 🔧 `v2-master-dev` (Development Branch)

**Purpose:** Integration and testing of new features
**Protection:** Protected, requires PR approval
**Updates:** From feature branches via PR
**CI/CD:** Full pipeline on every push

**Status:**
- ✅ Foundation complete (100% coverage)
- ✅ All infrastructure ready
- ⏳ Ready for protocol parser development

**Rules:**
- ❌ NEVER commit directly to v2-master-dev
- ✅ Only merge from feature/v2/* branches
- ✅ Must pass all CI/CD checks (100% coverage enforced)
- ✅ Requires code review
- ✅ Acts as staging for v2-master

**When to merge:**
- Feature is complete with 100% test coverage
- All CI/CD checks pass
- Code review approved
- Integration tests pass

### 🌿 `feature/v2/*` (Feature Branches)

**Purpose:** Development of individual features/tasks
**Protection:** None (local development)
**Updates:** Created from v2-master-dev
**CI/CD:** Full pipeline on push

**Naming Convention:**
```
feature/v2/<component>/<task-id>-<description>
```

**Examples:**
```
feature/v2/parsers/P2-002-uniswap-v2-base
feature/v2/parsers/P2-010-uniswap-v3-base
feature/v2/arbitrage/P5-001-path-finder
feature/v2/execution/P6-001-front-runner
feature/v2/cache/P3-006-liquidity-index
```

**Rules:**
- ✅ ALWAYS create from v2-master-dev
- ✅ Branch name MUST match task ID from planning docs
- ✅ One feature per branch
- ✅ Must achieve 100% test coverage
- ✅ Delete branch after merge
- ✅ Keep branches small and focused (< 2 hours work)

### 📦 `feature/v2-prep` (Foundation Branch - Archived)

**Purpose:** V2 planning and foundation implementation
**Status:** ✅ Complete and archived
**Protection:** Read-only

**What was implemented:**
- Complete planning documentation (7 docs)
- Core types and interfaces
- Parser factory
- Multi-index cache
- Validation pipeline
- Observability infrastructure
- CI/CD pipeline
- Git hooks

**Note:** This branch is now archived. All new development should branch from `v2-master-dev`.

---

## Workflow Examples

### 🎯 Standard Feature Development

```bash
# 1. Start from v2-master-dev
git checkout v2-master-dev
git pull origin v2-master-dev

# 2. Create feature branch
git checkout -b feature/v2/parsers/P2-002-uniswap-v2-base

# 3. Implement feature with TDD
# Write tests first, then implementation
make test-coverage  # Must show 100%

# 4. Validate locally
make validate  # Runs all CI/CD checks

# 5. Commit with conventional format
git add .
git commit -m "feat(parsers): implement UniswapV2 parser base

- Created parser struct with dependencies
- Implemented ParseLog() for Swap events
- Added comprehensive test suite
- Achieved 100% test coverage

Task: P2-002
Coverage: 100%
Tests: 42/42 passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"

# 6. Push and create PR
git push -u origin feature/v2/parsers/P2-002-uniswap-v2-base

# 7. Create PR on GitHub targeting v2-master-dev
# Wait for CI/CD to pass
# Get code review approval

# 8. Merge PR (squash and merge)
# Delete feature branch on GitHub

# 9. Cleanup local branch
git checkout v2-master-dev
git pull origin v2-master-dev
git branch -d feature/v2/parsers/P2-002-uniswap-v2-base
```

### 🚀 Production Release

```bash
# When v2-master-dev is stable and tested
git checkout v2-master
git pull origin v2-master

# Merge development into production
git merge --no-ff v2-master-dev -m "Release: Protocol parsers v1.0

Includes:
- UniswapV2 parser (100% coverage)
- UniswapV3 parser (100% coverage)
- Curve parser (100% coverage)
- Integration tests (all passing)

Total coverage: 100%
CI/CD: All checks passing"

# Push to production
git push origin v2-master

# Sync v2-master-dev
git checkout v2-master-dev
git merge v2-master
git push origin v2-master-dev
```

### 🔄 Hotfix for Production

```bash
# Create hotfix branch from v2-master
git checkout v2-master
git pull origin v2-master
git checkout -b hotfix/fix-decimal-precision

# Fix the issue with tests
# ... implement fix ...
make test-coverage  # Must show 100%
make validate

# Commit
git commit -m "fix(types): correct decimal scaling for USDC

- Fixed scaleToDecimals() rounding issue
- Added test case for 6-decimal tokens
- Verified against production data

Coverage: 100%
Tests: 156/156 passing"

# Merge to both v2-master and v2-master-dev
git checkout v2-master
git merge --no-ff hotfix/fix-decimal-precision
git push origin v2-master

git checkout v2-master-dev
git merge hotfix/fix-decimal-precision
git push origin v2-master-dev

# Delete hotfix branch
git branch -d hotfix/fix-decimal-precision
```

---

## Branch Protection Rules

### v2-master

- ✅ Require pull request before merging
- ✅ Require 1 approval
- ✅ Require status checks to pass:
  - Pre-flight checks
  - Build & dependencies
  - Code quality (40+ linters)
  - **100% test coverage (enforced)**
  - Integration tests
  - Modularity validation
- ✅ Require conversation resolution
- ✅ Require linear history
- ❌ Do not allow bypassing

### v2-master-dev

- ✅ Require pull request before merging
- ✅ Require 1 approval
- ✅ Require status checks to pass:
  - All CI/CD checks
  - **100% test coverage (enforced)**
- ✅ Require conversation resolution
- ❌ Do not allow bypassing

---

## CI/CD Pipeline

### Triggers

**On Push to:**
- `v2-master`
- `v2-master-dev`
- `feature/v2/**`

**On Pull Request to:**
- `v2-master`
- `v2-master-dev`

### Checks

All branches must pass:

1. **Pre-flight**
   - Branch naming validation
   - Commit message format

2. **Build & Dependencies**
   - Go compilation
   - Dependency verification
   - go.mod tidiness

3. **Code Quality**
   - gofmt formatting
   - go vet static analysis
   - golangci-lint (40+ linters)
   - gosec security scanning

4. **Tests**
   - Unit tests with race detector
   - **100% coverage enforcement** ⚠️
   - Integration tests
   - Decimal precision tests

5. **Modularity**
   - Component independence
   - No circular dependencies

6. **Performance**
   - Benchmarks (when requested)

### Coverage Enforcement

```bash
# CI/CD fails if coverage < 100%
COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | sed 's/%//')

if [ $(echo "$COVERAGE < 100" | bc -l) -eq 1 ]; then
    echo "❌ COVERAGE FAILURE: $COVERAGE% < 100%"
    exit 1
fi
```

**This is non-negotiable.** All code must have 100% test coverage.

---

## Current Status

### ✅ Complete

**v2-master** (Production)
- Foundation: 100% complete
- Test Coverage: 100% (enforced)
- Documentation: Complete
- CI/CD: Configured and tested

**v2-master-dev** (Development)
- Foundation: 100% complete
- Test Coverage: 100% (enforced)
- Ready for: Protocol parser development

**feature/v2-prep** (Archived)
- Planning: 7 comprehensive documents
- Foundation: Complete implementation
- Status: Archived, read-only

### ⏳ In Progress

**Phase 2:** Protocol Parser Implementations
- UniswapV2 parser
- UniswapV3 parser
- Curve parser
- Balancer V2 parser
- Kyber parsers
- Camelot parsers

### 📋 Planned

**Phase 3:** Arbitrage Detection
**Phase 4:** Execution Engine
**Phase 5:** Sequencer Integration

---

## Best Practices

### ✅ DO

- Create feature branches from `v2-master-dev`
- Follow the naming convention strictly
- Write tests before implementation (TDD)
- Run `make validate` before pushing
- Keep commits small and focused
- Use conventional commit messages
- Delete branches after merge
- Review planning docs before implementation

### ❌ DON'T

- Never commit directly to protected branches
- Never bypass CI/CD checks
- Never merge without 100% coverage
- Never skip code review
- Don't create long-lived feature branches
- Don't implement without tests
- Don't merge failing builds

---

## Quick Reference

### Commands

```bash
# Create feature branch
git checkout v2-master-dev
git pull
git checkout -b feature/v2/<component>/<task-id>-<description>

# Validate locally
make validate

# Test with coverage
make test-coverage

# Create PR (via GitHub UI or gh CLI)
gh pr create --base v2-master-dev --title "feat: description"

# Merge to production
git checkout v2-master
git merge --no-ff v2-master-dev
git push origin v2-master
```

### Branch Overview

| Branch | Purpose | Source | Protection | Coverage |
|--------|---------|--------|------------|----------|
| `v2-master` | Production | `v2-master-dev` | Protected | 100% |
| `v2-master-dev` | Development | `feature/v2/*` | Protected | 100% |
| `feature/v2/*` | Features | `v2-master-dev` | None | 100% |
| `feature/v2-prep` | Foundation | - | Archived | 100% |

### Coverage Requirements

All branches: **100% test coverage (enforced by CI/CD)**

No exceptions. No workarounds.

---

## Resources

- **Planning:** `docs/planning/`
- **Status:** `docs/V2_IMPLEMENTATION_STATUS.md`
- **Guidance:** `CLAUDE.md`
- **Overview:** `README.md`
- **CI/CD:** `.github/workflows/v2-ci.yml`
- **Hooks:** `.git-hooks/`

---

**Last Updated:** 2025-11-10
**Status:** v2-master and v2-master-dev created and synced
**Foundation:** ✅ Complete with 100% coverage
**Next:** Protocol parser implementations