trader-ml/docs/CONTRIBUTING.md

🤝 Guide de Contribution - Trading AI Secure

📋 Table des Matières

1. Code of Conduct
2. Comment Contribuer
3. Standards de Code
4. Workflow Git
5. Tests
6. Documentation
7. Review Process

---

📜 Code of Conduct

Nos Valeurs

• Respect : Traiter tous les contributeurs avec respect
• Collaboration : Travailler ensemble vers un objectif commun
• Excellence : Viser la qualité dans tout ce que nous faisons
• Transparence : Communication ouverte et honnête
• Sécurité : Priorité absolue dans le trading

Comportements Attendus

✅ Être accueillant et inclusif
✅ Respecter les opinions différentes
✅ Accepter les critiques constructives
✅ Se concentrer sur ce qui est meilleur pour la communauté
✅ Faire preuve d'empathie

Comportements Inacceptables

❌ Langage ou images inappropriés
❌ Attaques personnelles ou politiques
❌ Harcèlement public ou privé
❌ Publication d'informations privées sans permission
❌ Conduite non professionnelle

---

🚀 Comment Contribuer

Types de Contributions

1. Rapporter des Bugs

Template Issue Bug :

**Description du Bug**
Description claire et concise du bug.

**Étapes pour Reproduire**
1. Aller à '...'
2. Cliquer sur '...'
3. Voir erreur

**Comportement Attendu**
Ce qui devrait se passer.

**Comportement Actuel**
Ce qui se passe réellement.

**Screenshots**
Si applicable.

**Environnement**
- OS: [e.g. Windows 11]
- Python: [e.g. 3.11.5]
- Version: [e.g. 0.1.0]

**Logs**

Coller logs pertinents

2. Proposer des Features

Template Issue Feature :

**Problème à Résoudre**
Description du problème que cette feature résout.

**Solution Proposée**
Description de la solution.

**Alternatives Considérées**
Autres approches envisagées.

**Contexte Additionnel**
Informations supplémentaires.

3. Améliorer la Documentation

• Corriger typos
• Clarifier explications
• Ajouter exemples
• Traduire documentation

4. Développer du Code

• Nouvelles stratégies
• Améliorations ML
• Optimisations performance
• Nouveaux connecteurs de données

---

💻 Standards de Code

Style Python (PEP 8)

# ✅ BON
def calculate_position_size(
    portfolio_value: float,
    risk_per_trade: float,
    stop_distance: float
) -> float:
    """
    Calcule taille position optimale.
    
    Args:
        portfolio_value: Valeur totale du portfolio
        risk_per_trade: Risque par trade (0.0 à 1.0)
        stop_distance: Distance au stop-loss
        
    Returns:
        Taille de position en unités
        
    Raises:
        ValueError: Si paramètres invalides
    """
    if portfolio_value <= 0:
        raise ValueError("Portfolio value must be positive")
    
    risk_amount = portfolio_value * risk_per_trade
    position_size = risk_amount / stop_distance
    
    return position_size


# ❌ MAUVAIS
def calc_pos(pv,rpt,sd):
    return pv*rpt/sd

Type Hints (Obligatoires)

# ✅ BON
from typing import Dict, List, Optional
from datetime import datetime

def analyze_market(
    data: pd.DataFrame,
    timeframe: str,
    indicators: List[str]
) -> Optional[Dict[str, float]]:
    pass


# ❌ MAUVAIS
def analyze_market(data, timeframe, indicators):
    pass

Docstrings (Google Style)

def backtest_strategy(
    strategy: BaseStrategy,
    data: pd.DataFrame,
    initial_capital: float = 10000.0
) -> Dict[str, float]:
    """
    Backtest une stratégie sur données historiques.
    
    Cette fonction exécute un backtest complet incluant:
    - Simulation des trades
    - Calcul des métriques
    - Gestion du risque
    
    Args:
        strategy: Instance de stratégie à tester
        data: DataFrame avec données OHLCV
        initial_capital: Capital initial en USD
        
    Returns:
        Dictionnaire avec métriques:
            - 'total_return': Return total (%)
            - 'sharpe_ratio': Sharpe ratio
            - 'max_drawdown': Drawdown maximum (%)
            - 'win_rate': Taux de réussite (%)
            
    Raises:
        ValueError: Si données insuffisantes
        
    Example:
        >>> strategy = ScalpingStrategy(config)
        >>> data = load_historical_data('EURUSD', '1h')
        >>> results = backtest_strategy(strategy, data)
        >>> print(f"Sharpe: {results['sharpe_ratio']:.2f}")
        Sharpe: 1.85
    """
    pass

Naming Conventions

# Classes: PascalCase
class RiskManager:
    pass

# Functions/Methods: snake_case
def calculate_sharpe_ratio():
    pass

# Constants: UPPER_SNAKE_CASE
MAX_POSITION_SIZE = 0.05
DEFAULT_RISK_PER_TRADE = 0.02

# Private: _leading_underscore
def _internal_helper():
    pass

# Variables: snake_case
portfolio_value = 10000.0
current_drawdown = 0.05

Imports Organization

# 1. Standard library
import os
import sys
from datetime import datetime, timedelta
from typing import Dict, List, Optional

# 2. Third-party
import numpy as np
import pandas as pd
from fastapi import FastAPI, HTTPException

# 3. Local
from src.core.risk_manager import RiskManager
from src.strategies.base_strategy import BaseStrategy
from src.utils.logger import get_logger

---

🌿 Workflow Git

Branches

main
├── develop
│   ├── feature/add-new-strategy
│   ├── feature/improve-ml-engine
│   ├── bugfix/fix-risk-calculation
│   └── hotfix/critical-security-patch

Conventions de nommage :

• feature/description : Nouvelles fonctionnalités
• bugfix/description : Corrections de bugs
• hotfix/description : Corrections urgentes
• docs/description : Documentation
• refactor/description : Refactoring
• test/description : Ajout de tests

Workflow Contribution

1. Fork et Clone

# Fork sur GitHub
# Puis cloner votre fork
git clone https://github.com/VOTRE-USERNAME/trading-ai-secure.git
cd trading-ai-secure

# Ajouter upstream
git remote add upstream https://github.com/ORIGINAL-OWNER/trading-ai-secure.git

2. Créer Branche

# Mettre à jour develop
git checkout develop
git pull upstream develop

# Créer branche feature
git checkout -b feature/ma-nouvelle-feature

3. Développer

# Faire vos modifications
# ...

# Commiter régulièrement
git add .
git commit -m "feat: add new scalping indicator"

# Suivre conventions de commit (voir ci-dessous)

4. Tester

# Lancer tests
pytest tests/

# Vérifier couverture
pytest --cov=src tests/

# Linter
pylint src/
black src/
isort src/

5. Push et Pull Request

# Push vers votre fork
git push origin feature/ma-nouvelle-feature

# Créer Pull Request sur GitHub
# Remplir template PR

Conventions de Commit

Format : <type>(<scope>): <description>

Types :

• feat: Nouvelle fonctionnalité
• fix: Correction de bug
• docs: Documentation
• style: Formatage (pas de changement de code)
• refactor: Refactoring
• test: Ajout de tests
• chore: Maintenance

Exemples :

feat(strategies): add VWAP indicator to intraday strategy
fix(risk): correct position sizing calculation
docs(readme): update installation instructions
test(backtesting): add Monte Carlo simulation tests
refactor(ml): optimize feature engineering pipeline

---

🧪 Tests

Structure Tests

tests/
├── unit/
│   ├── test_risk_manager.py
│   ├── test_strategies.py
│   └── test_ml_engine.py
├── integration/
│   ├── test_data_sources.py
│   └── test_ig_api.py
├── e2e/
│   └── test_full_trading_loop.py
└── fixtures/
    └── sample_data.py

Écrire Tests

# tests/unit/test_risk_manager.py

import pytest
from src.core.risk_manager import RiskManager

class TestRiskManager:
    """Tests pour RiskManager"""
    
    @pytest.fixture
    def risk_manager(self):
        """Fixture RiskManager"""
        return RiskManager()
    
    def test_singleton_pattern(self):
        """Vérifie pattern singleton"""
        rm1 = RiskManager()
        rm2 = RiskManager()
        assert rm1 is rm2
    
    def test_validate_trade_success(self, risk_manager):
        """Test validation trade valide"""
        is_valid, error = risk_manager.validate_trade(
            symbol='EURUSD',
            quantity=1000,
            price=1.1000,
            stop_loss=1.0950,
            take_profit=1.1100,
            strategy='intraday'
        )
        
        assert is_valid is True
        assert error is None
    
    def test_validate_trade_no_stop_loss(self, risk_manager):
        """Test rejet si pas de stop-loss"""
        is_valid, error = risk_manager.validate_trade(
            symbol='EURUSD',
            quantity=1000,
            price=1.1000,
            stop_loss=None,  # Pas de stop-loss
            take_profit=1.1100,
            strategy='intraday'
        )
        
        assert is_valid is False
        assert "stop-loss" in error.lower()
    
    @pytest.mark.parametrize("position_size,expected", [
        (0.01, True),   # 1% OK
        (0.05, True),   # 5% OK
        (0.10, False),  # 10% trop grand
    ])
    def test_position_size_limits(self, risk_manager, position_size, expected):
        """Test limites taille position"""
        # ... test paramétré

Coverage Minimum

• Global : 85%
• Core modules : 90%
• Stratégies : 85%
• ML : 80%
• UI : 70%

---

📚 Documentation

Documentation Code

Chaque module doit avoir :

1. Module docstring : Description du module
2. Class docstrings : Description de la classe
3. Method docstrings : Description des méthodes
4. Type hints : Sur tous les paramètres et retours

Documentation Utilisateur

Mettre à jour si changements :

• README.md : Vue d'ensemble
• docs/GETTING_STARTED.md : Guide démarrage
• docs/ARCHITECTURE.md : Architecture
• docs/API.md : Documentation API

Exemples

Ajouter exemples d'utilisation :

# examples/strategies/custom_strategy_example.py

"""
Exemple de création d'une stratégie custom.

Cet exemple montre comment:
- Hériter de BaseStrategy
- Implémenter les méthodes requises
- Configurer les paramètres
- Backtester la stratégie
"""

from src.strategies.base_strategy import BaseStrategy

class MyCustomStrategy(BaseStrategy):
    """Ma stratégie personnalisée"""
    
    def analyze(self, data):
        # Implémentation
        pass

# Usage
if __name__ == "__main__":
    strategy = MyCustomStrategy(config)
    results = backtest_strategy(strategy, data)
    print(results)

---

👀 Review Process

Checklist PR

Avant de soumettre PR, vérifier :

• Code suit standards (PEP 8, type hints, docstrings)
• Tests ajoutés et passent (coverage > 85%)
• Documentation mise à jour
• Pas de secrets/credentials dans le code
• Commits suivent conventions
• Branch à jour avec develop
• Pas de conflits

Template Pull Request

## Description
Description claire des changements.

## Type de Changement
- [ ] Bug fix
- [ ] Nouvelle feature
- [ ] Breaking change
- [ ] Documentation

## Tests
- [ ] Tests unitaires ajoutés
- [ ] Tests d'intégration ajoutés
- [ ] Tous les tests passent
- [ ] Coverage > 85%

## Checklist
- [ ] Code suit standards
- [ ] Documentation mise à jour
- [ ] Pas de secrets dans le code
- [ ] Commits conventionnels

## Screenshots (si applicable)

## Notes Additionnelles

Process de Review

1. Automated Checks : CI/CD vérifie tests, linting
2. Code Review : Au moins 1 reviewer approuve
3. Testing : Reviewer teste localement
4. Merge : Squash and merge vers develop

---

🎯 Priorités Contributions

High Priority

• 🔴 Corrections de bugs critiques
• 🔴 Améliorations sécurité
• 🔴 Optimisations performance

Medium Priority

• 🟡 Nouvelles stratégies
• 🟡 Améliorations ML
• 🟡 Documentation

Low Priority

• 🟢 Refactoring
• 🟢 Optimisations mineures
• 🟢 Traductions

---

💬 Communication

Channels

• GitHub Issues : Bugs, features
• GitHub Discussions : Questions, idées
• Discord : Chat temps réel
• Email : contact@trading-ai-secure.com

Réponse

• Issues : < 48h
• PRs : < 72h
• Questions : < 24h

---

🏆 Reconnaissance

Les contributeurs sont reconnus dans :

• CONTRIBUTORS.md
• Release notes
• Documentation

---

Merci de contribuer à Trading AI Secure ! 🚀