mev-beta/docs/BRANCH_STRATEGY.md

Branch Strategy for MEV Bot Project

This document outlines the branching strategy for the MEV Bot project.

Branch Types

1. Main Branches

main

• Contains production-ready code
• Only accepts merges from release/* branches
• Always stable and deployable
• Protected branch - requires pull requests and code review

develop

• Main development branch
• Contains latest delivered development changes
• All feature branches merge here
• Automated CI/CD pipeline runs on this branch

2. Supporting Branches

feature/*

• Used for developing new features
• Branch from: develop
• Merge back to: develop
• Branch naming: feature/<descriptive-name>
• Examples:
  • feature/add-market-scanner
  • feature/improve-uniswap-pricing
  • feature/add-logging

fix/*

• Used for bug fixes in development
• Branch from: develop
• Merge back to: develop
• Branch naming: fix/<descriptive-name>
• Examples:
  • fix/resolve-memory-leak
  • fix/correct-pricing-calculation

release/*

• Used for release preparation
• Branch from: develop
• Merge back to: main and develop
• Branch naming: release/<version>
• Examples:
  • release/v1.2.0
  • release/v2.0.0

hotfix/*

• Used for critical production fixes
• Branch from: main
• Merge back to: main and develop
• Branch naming: hotfix/<descriptive-name>
• Examples:
  • hotfix/security-patch
  • hotfix/critical-bug-fix

Workflow Examples

Feature Development Workflow

# 1. Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/add-market-scanner

# 2. Develop feature
# ... make changes ...
git add .
git commit -m "feat(market): implement basic market scanner"

# 3. Keep feature branch up to date
git checkout develop
git pull origin develop
git checkout feature/add-market-scanner
git rebase develop

# 4. Push feature branch
git push -u origin feature/add-market-scanner

# 5. Create Pull Request on GitHub/GitLab
# 6. After PR approval and merge, delete branch
git checkout develop
git pull origin develop
git branch -d feature/add-market-scanner
git push origin --delete feature/add-market-scanner

Release Workflow

# 1. Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# 2. Prepare release
# ... bump version numbers, update docs ...
git add .
git commit -m "chore(release): prepare v1.2.0"

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

# 4. Merge to develop
git checkout develop
git pull origin develop
git merge release/v1.2.0
git push origin develop

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

Hotfix Workflow

# 1. Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-issue

# 2. Fix issue
# ... make changes ...
git add .
git commit -m "fix(security): resolve critical vulnerability"

# 3. Merge to main
git checkout main
git pull origin main
git merge hotfix/critical-security-issue
git tag -a v1.1.1 -m "Hotfix v1.1.1"
git push origin main --tags

# 4. Merge to develop
git checkout develop
git pull origin develop
git merge hotfix/critical-security-issue
git push origin develop

# 5. Delete hotfix branch
git branch -d hotfix/critical-security-issue
git push origin --delete hotfix/critical-security-issue

Branch Protection Rules

main Branch

• Require pull request reviews before merging
• Require status checks to pass before merging
• Require branches to be up to date before merging
• Include administrators in restrictions
• Allow force pushes: No
• Allow deletions: No

develop Branch

• Require pull request reviews before merging
• Require status checks to pass before merging
• Include administrators in restrictions
• Allow force pushes: No
• Allow deletions: No

Naming Conventions

Good Examples

• feature/add-uniswap-v3-support
• fix/resolve-arbitrum-parser-bug
• release/v2.1.0
• hotfix/security-patch

Avoid These

• feature/fix (unclear)
• bugfix (use fix/ instead)
• new-stuff (not descriptive)
• feature1 (not descriptive)

Best Practices

1. Keep branches short-lived - Max 1-2 weeks
2. Use descriptive names - Clearly indicate purpose
3. Keep features small - One branch per logical feature
4. Regularly sync with develop - Prevent large merge conflicts
5. Delete branches after merging - Keep repository clean
6. Use pull requests - Enable code review and discussion
7. Write meaningful commit messages - Help with code review
8. Tag releases - Enable easy rollback and version tracking

This branching strategy ensures a clean, organized Git history while enabling parallel development and maintaining code quality.