MQL5-Google-Onedrive/CONTRIBUTING.md

Contributing to MQL5 Trading Automation

Thank you for your interest in contributing to this project! This guide outlines the standards and practices we follow.

📋 Table of Contents

• Code of Conduct
• Getting Started
• Development Workflow
• Coding Standards
• Testing Guidelines
• Documentation Standards
• Commit Message Guidelines
• Pull Request Process

Code of Conduct

This project adheres to a code of professional conduct. By participating, you agree to:

• Be respectful and inclusive
• Focus on constructive feedback
• Accept responsibility for your contributions
• Prioritize the project's best interests

Getting Started

Prerequisites

• Python 3.8+
• Docker and Docker Compose
• Git
• MetaTrader 5 (for MQL5 development)
• VS Code (recommended)

Initial Setup

1. Clone the repository:

   git clone https://github.com/A6-9V/MQL5-Google-Onedrive.git
   cd MQL5-Google-Onedrive
   

2. Open the workspace:

   code MQL5-Trading-Automation.code-workspace
   

3. Install dependencies:

   pip install -r requirements.txt
   pip install -r scripts/requirements_bot.txt
   

4. Validate your setup:

   python scripts/ci_validate_repo.py
   python scripts/test_automation.py
   

Development Workflow

Branch Strategy

• main - Production-ready code
• develop - Integration branch for features
• feature/* - New features
• fix/* - Bug fixes
• docs/* - Documentation updates

Creating a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Coding Standards

General Principles

1. Keep it Simple: Write clear, maintainable code
2. DRY (Don't Repeat Yourself): Avoid code duplication
3. Single Responsibility: Each function/class should have one purpose
4. Explicit is Better: Use clear variable and function names
5. Test Your Code: Write tests for new functionality

Python Code Standards

• Style Guide: Follow PEP 8
• Formatting: Use black for automatic formatting
• Linting: Use pylint to catch errors
• Type Hints: Use type hints where appropriate

# Good example
def calculate_lot_size(
    risk_percent: float,
    stop_loss_points: int,
    account_balance: float
) -> float:
    """Calculate position size based on risk parameters.
    
    Args:
        risk_percent: Risk percentage (0-100)
        stop_loss_points: Stop loss distance in points
        account_balance: Account balance in base currency
        
    Returns:
        Calculated lot size
    """
    risk_amount = account_balance * (risk_percent / 100)
    lot_size = risk_amount / (stop_loss_points * 10)
    return round(lot_size, 2)

MQL5 Code Standards

• Naming: Use PascalCase for functions, camelCase for variables
• Comments: Use // for single-line, /* */ for multi-line
• Input Variables: Group related inputs together
• Error Handling: Always check return values

// Good example
input group "Risk Management"
input double RiskPercent = 1.0;        // Risk per trade (%)
input bool   RiskUseEquity = true;     // Use equity instead of balance

//+------------------------------------------------------------------+
//| Calculate lot size based on risk                                  |
//+------------------------------------------------------------------+
double CalculateLotSize(double slDistance)
{
    if (slDistance <= 0) return 0.0;
    
    double accountSize = RiskUseEquity ? AccountInfoDouble(ACCOUNT_EQUITY) 
                                       : AccountInfoDouble(ACCOUNT_BALANCE);
    double riskAmount = accountSize * (RiskPercent / 100.0);
    
    double pointValue = SymbolInfoDouble(_Symbol, SYMBOL_TRADE_TICK_VALUE);
    double lotSize = riskAmount / (slDistance * pointValue);
    
    return NormalizeLots(lotSize);
}

Bash/Shell Script Standards

• Use #!/bin/bash shebang
• Use set -e for exit on error
• Quote all variables: "$variable"
• Use functions for reusability
• Add help text with -h flag

#!/bin/bash
set -e

# Good example
function validate_file() {
    local file="$1"
    
    if [[ ! -f "$file" ]]; then
        echo "Error: File not found: $file"
        return 1
    fi
    
    return 0
}

Docker Standards

• Use multi-stage builds where appropriate
• Keep images small (use Alpine when possible)
• Don't run as root user
• Pin base image versions
• Use .dockerignore to exclude unnecessary files

Testing Guidelines

Required Tests

1. Unit Tests: Test individual functions
2. Integration Tests: Test component interactions
3. Validation Tests: Ensure code meets requirements

Running Tests

# Run repository validation
python scripts/ci_validate_repo.py

# Run automation tests
python scripts/test_automation.py

# Package MT5 files (smoke test)
bash scripts/package_mt5.sh

Writing Tests

# Example test structure
import pytest

def test_calculate_lot_size():
    """Test lot size calculation."""
    result = calculate_lot_size(
        risk_percent=1.0,
        stop_loss_points=50,
        account_balance=10000.0
    )
    
    assert result > 0
    assert result <= 10.0  # Reasonable max lot size

Documentation Standards

Code Documentation

• Functions: Always include docstrings
• Classes: Document purpose and usage
• Complex Logic: Add inline comments explaining why
• TODOs: Mark with TODO: and your initials

Markdown Documentation

• Use clear headings (h1-h6)
• Include table of contents for long documents
• Use code blocks with language syntax highlighting
• Keep lines under 100 characters when possible
• Use relative links for internal documents

README Updates

When making changes that affect usage:

1. Update the main README.md
2. Update relevant documentation in docs/
3. Update CHANGELOG.md
4. Ensure all links work

Commit Message Guidelines

We follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• perf: Performance improvements
• ci: CI/CD changes

Examples

feat(ea): add Gemini AI integration for trade confirmation

Implement AI-powered trade confirmation using Google Gemini API.
Users can now enable AI filtering to get intelligent trade analysis
before entry.

Closes #123

---

fix(scripts): correct path handling in package_mt5.sh

The script was using relative paths incorrectly on Windows.
Changed to use absolute paths with proper path resolution.

---

docs: update README with new workspace configuration

Add instructions for using the new VS Code workspace file.

Pull Request Process

Before Submitting

1. Test your changes:

   python scripts/ci_validate_repo.py
   python scripts/test_automation.py
   

2. Update documentation if needed

3. Format your code:

   black scripts/*.py
   

4. Check your commits follow the guidelines

PR Template

Use the provided PR template. Include:

• Clear description of changes
• Link to related issues
• Screenshots (for UI changes)
• Testing performed
• Breaking changes (if any)

Review Process

1. Automated checks must pass (CI/CD)
2. Code review by at least one maintainer
3. Testing in the reviewer's environment
4. Documentation review if docs changed
5. Merge after approval

Auto-merge

PRs with the automerge label will auto-merge once:

• All required checks pass
• Required reviews are approved
• No conflicts exist

Development Environment

Using DevContainer

The project includes a DevContainer configuration:

# Open in VS Code with DevContainer extension
code MQL5-Trading-Automation.code-workspace
# Press F1 -> "Dev Containers: Reopen in Container"

Using Docker Compose

# Development environment
docker-compose -f docker-compose.dev.yml up -d

# Enter the container
docker exec -it mql5-trading-dev bash

# Run tests inside container
python scripts/ci_validate_repo.py

Manual Setup

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
pip install -r scripts/requirements_bot.txt

File Organization

.
├── .devcontainer/        # DevContainer configuration
├── .github/              # GitHub workflows and templates
├── .vscode/              # VS Code settings
├── config/               # Configuration files
├── dashboard/            # Web dashboard files
├── docs/                 # Documentation
├── mt5/MQL5/            # MQL5 source code
│   ├── Experts/         # Expert Advisors
│   ├── Indicators/      # Indicators
│   └── Include/         # Shared libraries
├── scripts/             # Automation scripts
└── MQL5-Trading-Automation.code-workspace  # VS Code workspace

Getting Help

• Documentation: Check docs/INDEX.md for all guides
• Issues: Open an issue on GitHub
• Questions: Use GitHub Discussions
• Community: Join our WhatsApp Agent Community

License

By contributing, you agree that your contributions will be licensed under the same license as the project (see LICENSE file).

---

Thank you for contributing! 🚀