docs: add comprehensive branch structure documentation
Created detailed branch structure guide for V2 development:
Branch Hierarchy:
- v2-master (production, protected)
└── v2-master-dev (development, protected)
└── feature/v2/* (feature branches)
Documented Branches:
- v2-master: Production-ready code, protected, 100% coverage
- v2-master-dev: Integration/testing, protected, 100% coverage
- feature/v2/*: Feature development, atomic tasks
- feature/v2-prep: Foundation (archived, complete)
Workflow Examples:
- Standard feature development (9 steps)
- Production release process
- Hotfix workflow for urgent fixes
Branch Protection Rules:
- Require PR before merge
- Require 1+ approval
- Require all CI/CD checks pass
- 100% coverage enforced
- No direct commits to protected branches
CI/CD Pipeline:
- Triggers on all branches
- Pre-flight, build, quality, tests, modularity
- Coverage enforcement (fails if < 100%)
- Performance benchmarks
Best Practices:
- DO: TDD, conventional commits, make validate
- DON'T: Direct commits, bypass CI/CD, skip tests
Quick Reference:
- Common commands
- Branch overview table
- Coverage requirements (100% non-negotiable)
Foundation Status: ✅ Complete
Next Phase: Protocol parser implementations
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Administrator
450
docs/BRANCH_STRUCTURE.md
Normal file
450
docs/BRANCH_STRUCTURE.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user