Hugging Face's logo

ParallelLLC
/
algorithmic_trading

Model card Files
xet
Community
algorithmic_trading / BRANCH_PROTECTION_RULES.md
Edwin Salguero
feat: Add comprehensive branch protection and release management
a13907f
preview code
|
raw
history blame contribute delete
9.79 kB

🛡️ Branch Protection Rules & Release Guidelines

This document outlines the recommended branch protection rules and release management guidelines for the Algorithmic Trading System.

🔒 Branch Protection Rules

Main Branch Protection

Required Status Checks 

# Quality Assurance
- ci-cd/quality-check
- ci-cd/test
- ci-cd/security

# Trading-Specific
- ci-cd/backtesting
- ci-cd/model-training

# Deployment
- ci-cd/docker-build
- ci-cd/docker-push

Required Reviews 

# Code Review Requirements
- Require pull request reviews: 2
- Dismiss stale reviews: true
- Require review from code owners: true
- Require review from trading experts: true

# Review Restrictions
- Restrict pushes: true
- Allow force pushes: false
- Allow deletions: false

Code Quality Gates 

# Test Coverage
- Minimum coverage: 80%
- Coverage decrease threshold: 5%

# Security Requirements
- No critical vulnerabilities
- No high severity issues
- Security scan passed

# Performance Requirements
- Strategy backtesting passed
- Performance benchmarks met
- Risk limits validated

Development Branch Rules

Feature Branches 

# Naming Convention
- Pattern: feature/description
- Examples: feature/new-strategy, feature/risk-management

# Protection Level
- Require status checks: ci-cd/quality-check, ci-cd/test
- Require reviews: 1
- Allow force pushes: false

Hotfix Branches 

# Naming Convention
- Pattern: hotfix/issue-description
- Examples: hotfix/critical-bug, hotfix/security-patch

# Protection Level
- Require status checks: ALL
- Require reviews: 2
- Require trading expert approval
- Allow force pushes: false

🏷️ Release Management Guidelines

Version Numbering (Semantic Versioning) 

# Format: MAJOR.MINOR.PATCH
- MAJOR: Breaking changes, major strategy updates
- MINOR: New features, strategy enhancements
- PATCH: Bug fixes, security patches

# Examples
- v1.0.0: Initial release
- v1.1.0: New trading strategy added
- v1.1.1: Bug fix in risk management
- v2.0.0: Major architecture change

Release Types

Major Releases (vX.0.0)

Requirements:

  • ✅ Full test suite passes
  • ✅ Security audit completed
  • ✅ Performance benchmarks met
  • ✅ Trading expert approval
  • ✅ Risk management review
  • ✅ Documentation updated
  • ✅ Migration guide provided

Examples:

  • New trading algorithm implementation
  • Major FinRL model architecture change
  • Significant API changes
  • Risk management system overhaul

Minor Releases (vX.Y.0)

Requirements:

  • ✅ All tests pass
  • ✅ Backtesting validation
  • ✅ Performance impact assessed
  • ✅ Code review completed
  • ✅ Documentation updated

Examples:

  • New technical indicators
  • Strategy parameter optimization
  • Enhanced risk controls
  • New data sources

Patch Releases (vX.Y.Z)

Requirements:

  • ✅ Regression tests pass
  • ✅ Security scan clean
  • ✅ Quick review by maintainer
  • ✅ Release notes updated

Examples:

  • Bug fixes
  • Security patches
  • Performance optimizations
  • Documentation corrections

Release Process

1. Pre-Release Checklist 

# Code Quality
- [ ] All CI/CD checks pass
- [ ] Code coverage > 80%
- [ ] No security vulnerabilities
- [ ] Performance benchmarks met

# Trading Validation
- [ ] Strategy backtesting passed
- [ ] Risk limits validated
- [ ] Model performance acceptable
- [ ] Compliance checks passed

# Documentation
- [ ] README updated
- [ ] API documentation current
- [ ] Changelog prepared
- [ ] Migration notes (if needed)

2. Release Creation 

# Create release branch
git checkout -b release/v1.2.0

# Update version
# Update CHANGELOG.md
# Update documentation

# Create tag
git tag -a v1.2.0 -m "Release v1.2.0: Enhanced risk management"

# Push tag (triggers release workflow)
git push origin v1.2.0

3. Post-Release Validation 

# Automated Checks
- [ ] Docker image built successfully
- [ ] Documentation deployed
- [ ] Release notes published
- [ ] Notifications sent

# Manual Verification
- [ ] Test deployment in staging
- [ ] Strategy performance validation
- [ ] Risk management verification
- [ ] User acceptance testing

🚨 Critical Trading Rules

Risk Management Validation 

# Position Limits
- Maximum position size: 100 shares
- Maximum portfolio allocation: 5%
- Maximum drawdown: 5%

# Strategy Validation
- Minimum Sharpe ratio: 0.5
- Maximum volatility: 20%
- Minimum backtesting period: 6 months

# Compliance Checks
- Regulatory compliance verified
- Risk limits enforced
- Audit trail maintained

Emergency Procedures

Critical Bug in Production 

# Immediate Actions
1. Stop trading immediately
2. Create hotfix branch
3. Apply emergency patch
4. Deploy to production
5. Notify stakeholders

# Post-Emergency
1. Root cause analysis
2. Process improvement
3. Documentation update
4. Team review

Security Incident 

# Response Steps
1. Assess impact
2. Contain threat
3. Apply security patch
4. Verify fix
5. Deploy update
6. Monitor closely

📋 Code Owner Rules

CODEOWNERS File 

# Core Trading Logic
/agentic_ai_system/strategy_agent.py @trading-expert
/agentic_ai_system/finrl_agent.py @ml-expert
/agentic_ai_system/execution_agent.py @trading-expert

# Risk Management
/agentic_ai_system/risk_management.py @risk-expert
/config.yaml @trading-expert

# Infrastructure
/Dockerfile @devops-expert
/.github/ @devops-expert

# Documentation
/README.md @tech-writer
/docs/ @tech-writer

Review Requirements 

# Trading Code
- Must be reviewed by trading expert
- Must pass backtesting validation
- Must meet risk management criteria

# ML Models
- Must be reviewed by ML expert
- Must pass performance validation
- Must include model documentation

# Infrastructure
- Must be reviewed by DevOps expert
- Must pass security scan
- Must include deployment plan

🔍 Quality Gates

Automated Checks 

# Code Quality
- Black formatting check
- Flake8 linting (max 10 complexity)
- Type hints coverage > 90%
- Docstring coverage > 80%

# Security
- Bandit security scan
- Safety dependency check
- Trivy container scan
- Secret detection

# Performance
- Strategy execution time < 100ms
- Memory usage < 1GB
- CPU usage < 80%
- API response time < 500ms

Manual Reviews 

# Code Review Checklist
- [ ] Logic is correct
- [ ] Error handling adequate
- [ ] Performance acceptable
- [ ] Security considerations
- [ ] Documentation updated
- [ ] Tests added/updated

# Trading Review Checklist
- [ ] Strategy logic sound
- [ ] Risk management adequate
- [ ] Performance metrics acceptable
- [ ] Compliance requirements met
- [ ] Backtesting results validated

📊 Monitoring & Alerts

Release Monitoring 

# Success Metrics
- Deployment success rate > 95%
- Zero critical bugs in first 24h
- Performance maintained
- User satisfaction > 4.5/5

# Alert Thresholds
- Test failure rate > 5%
- Security vulnerability detected
- Performance degradation > 10%
- Trading error rate > 1%

Automated Notifications 

# Slack Channels
- #trading-alerts: Critical trading issues
- #deployment: Release status
- #security: Security incidents
- #performance: Performance alerts

# Email Notifications
- Release completion
- Critical failures
- Security incidents
- Performance degradation

🛠️ Implementation Guide

GitHub Settings

1. Branch Protection 

# Enable branch protection for main
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci-cd/quality-check","ci-cd/test","ci-cd/security"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":2,"dismiss_stale_reviews":true}' \
  --field restrictions=null

2. Required Status Checks 

# In GitHub UI: Settings > Branches > Add rule
Branch name pattern: main
Require status checks to pass before merging: ✅
Require branches to be up to date before merging: ✅
Status checks that are required:
- ci-cd/quality-check
- ci-cd/test
- ci-cd/security
- ci-cd/backtesting
- ci-cd/docker-build

3. Review Requirements 

# Pull Request Reviews
Require a pull request before merging: ✅
Require approvals: 2
Dismiss stale pull request approvals when new commits are pushed: ✅
Require review from code owners: ✅
Restrict pushes that create files: ✅

Release Automation

1. Release Workflow Trigger 

# Automatic on tag push
on:
  push:
    tags:
      - 'v*'

2. Release Validation 

# Pre-release checks
- All tests pass
- Security scan clean
- Performance benchmarks met
- Documentation updated

3. Post-release Monitoring 

# 24-hour monitoring
- Error rate monitoring
- Performance tracking
- User feedback collection
- Rollback preparation

📈 Success Metrics

Quality Metrics

  • Bug Rate: < 1% of releases
  • Security Incidents: 0 per quarter
  • Performance Degradation: < 5%
  • User Satisfaction: > 4.5/5

Process Metrics

  • Release Frequency: 2-4 weeks
  • Deployment Time: < 30 minutes
  • Rollback Time: < 10 minutes
  • Review Time: < 24 hours

Trading Metrics

  • Strategy Performance: > Benchmark
  • Risk Compliance: 100%
  • System Uptime: > 99.9%
  • Error Rate: < 0.1%

Note: These rules are specifically designed for algorithmic trading systems where code quality directly impacts financial performance and risk management.