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

# 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

# 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

# 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

# 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

# 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