From af2e9e9a1ff81e79c461693c0dba3c1d9778d580 Mon Sep 17 00:00:00 2001 From: Administrator Date: Mon, 10 Nov 2025 14:57:26 +0100 Subject: [PATCH] docs: add comprehensive branch structure documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/BRANCH_STRUCTURE.md | 450 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 450 insertions(+) create mode 100644 docs/BRANCH_STRUCTURE.md diff --git a/docs/BRANCH_STRUCTURE.md b/docs/BRANCH_STRUCTURE.md new file mode 100644 index 0000000..02a4522 --- /dev/null +++ b/docs/BRANCH_STRUCTURE.md @@ -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//- +``` + +**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 " + +# 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//- + +# 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