Contributing Guidelines

Welcome Contributors!

Thank you for your interest in contributing to the XAUUSD Trading Assistant AI project! We welcome contributions from the community to help improve this educational trading tool.

This is an open-source educational project. All contributions should align with the goal of helping others learn about algorithmic trading and AI integration.

Ways to Contribute

There are many ways you can contribute to this project:

Report Bugs

Found an issue? Report it on GitHub with detailed information to help us fix it.

Suggest Features

Have ideas for improvements? Share your feature requests and enhancement ideas.

Improve Documentation

Help make the documentation clearer, more comprehensive, and easier to understand.

Submit Code

Fix bugs, add features, or improve existing functionality with code contributions.

Getting Started

1. Fork and Clone the Repository

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/xauusd-trading-bot.git
cd xauusd-trading-bot

2. Set Up Development Environment

# Create a virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies (if available)
pip install -r requirements-dev.txt  # If exists

3. Create a Branch

# Create a new branch for your contribution
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Use descriptive branch names: feature/add-new-indicator, fix/mt5-connection-error, docs/update-installation-guide

Contribution Guidelines

Code Standards

Python Style Guide

Follow PEP 8 style guidelines:

Use 4 spaces for indentation (no tabs)
Maximum line length of 88 characters (Black formatter standard)
Use descriptive variable and function names
Add docstrings to functions and classes

Example:

def calculate_rsi(prices: list, period: int = 14) -> float:
    """
    Calculate the Relative Strength Index (RSI).
    
    Args:
        prices: List of price values
        period: RSI period (default: 14)
        
    Returns:
        RSI value as a float
    """
    # Implementation here
    pass

Code Quality

Ensure your code is:

Clean: Remove unnecessary comments and debug code
Efficient: Optimize for performance where possible
Readable: Use clear variable names and structure
Documented: Add comments for complex logic
Type-hinted: Use Python type hints where applicable

Consider using tools like black for formatting and pylint for linting.

Error Handling

Implement proper error handling:

try:
    # Code that might fail
    data = mt5.copy_rates_from_pos("XAUUSD", mt5.TIMEFRAME_H1, 0, 100)
    if data is None:
        raise ValueError("Failed to retrieve market data")
except Exception as e:
    logging.error(f"Error fetching data: {e}")
    # Handle error appropriately

Use try-except blocks for external dependencies
Log errors with appropriate severity levels
Provide meaningful error messages
Fail gracefully when possible

Dependencies

When adding new dependencies:

Justify why the dependency is needed
Use well-maintained, reputable packages
Update requirements.txt with pinned versions
Document any special installation steps

Example requirements.txt entry:

pandas==2.0.3  # Data manipulation
numpy==1.24.3  # Numerical operations

Testing Requirements

All code contributions should be tested thoroughly before submission.

Testing Checklist

Before submitting your contribution:

Test on a demo MT5 account
Verify existing functionality still works
Test edge cases and error conditions
Check with different timeframes
Verify Streamlit dashboard still loads
Test with various market conditions (if possible)
Ensure no hardcoded credentials or API keys

Unit Tests (Optional but Recommended)

If adding unit tests:

import unittest
from XAUSD_AI import calculate_rsi

class TestTechnicalIndicators(unittest.TestCase):
    def test_rsi_calculation(self):
        prices = [44, 44.34, 44.09, 43.61, 44.33]
        rsi = calculate_rsi(prices, period=14)
        self.assertIsNotNone(rsi)
        self.assertGreaterEqual(rsi, 0)
        self.assertLessEqual(rsi, 100)

if __name__ == '__main__':
    unittest.main()

Manual Testing

Document your testing process:

Test Environment:
- OS: Windows 10
- Python: 3.10.5
- MT5: Build 3650
Test Scenarios:
- Connected to demo account
- Ran analysis on XAUUSD
- Checked all timeframes
- Verified AI signal generation
Results:
- All features working as expected
- No errors in console
- Dashboard displays correctly

Documentation Standards

Code Documentation

Document your code appropriately:

Docstrings: Add to all functions and classes
Comments: Explain complex logic, not obvious code
Type hints: Use Python type annotations
Examples: Provide usage examples for new features

Example:

def identify_order_block(
    df: pd.DataFrame,
    threshold: float = 0.02
) -> dict:
    """
    Identify potential order blocks in price data.
    
    Order blocks are zones where institutional traders
    have placed significant orders.
    
    Args:
        df: DataFrame with OHLC data
        threshold: Minimum price movement to identify block (2%)
        
    Returns:
        Dictionary with order block details:
        {
            'level': float,
            'type': 'bullish' or 'bearish',
            'strength': float
        }
        
    Example:
        >>> data = get_market_data("XAUUSD", "H1")
        >>> block = identify_order_block(data)
        >>> print(f"Order block at {block['level']}")
    """
    # Implementation
    pass

README Updates

Update README.md if you:

Add new features
Change installation steps
Modify configuration requirements
Add new dependencies
Change usage instructions

Keep the README:

Clear and concise
Up-to-date with latest changes
Beginner-friendly
Well-formatted

Changelog

If a CHANGELOG.md exists, add your changes:

## [Unreleased]
### Added
- New Fibonacci retracement analysis feature
- Support for additional timeframes (M1, M3)

### Fixed
- MT5 connection timeout issue
- Spread calculation accuracy

### Changed
- Improved RSI calculation performance
- Updated AI prompt for better signal clarity

Submitting Contributions

Pull Request Process

Commit Your Changes

Make clean, logical commits:

git add .
git commit -m "Add: Fibonacci retracement analysis feature"

Commit Message Format:

Add: for new features
Fix: for bug fixes
Update: for improvements to existing features
Docs: for documentation changes
Refactor: for code refactoring
Test: for adding tests

Write clear, descriptive commit messages that explain what and why, not just what.

Push to Your Fork

git push origin feature/your-feature-name

Create Pull Request

Go to the original repository on GitHub
Click “New Pull Request”
Select your fork and branch
Fill out the PR template (if available)
Submit the pull request

PR Description

Provide a comprehensive description:

## Description
Added Fibonacci retracement analysis to identify key support/resistance levels.

## Changes Made
- Implemented `calculate_fibonacci()` function
- Added Fibonacci levels to Streamlit dashboard
- Updated AI prompt to consider Fibonacci levels
- Added documentation for new feature

## Testing
- Tested on demo MT5 account
- Verified across all timeframes
- Checked dashboard display
- No breaking changes to existing features

## Screenshots (if applicable)
[Add screenshots of new feature]

## Related Issues
Closes #123

PR Review Process

Be patient during the review process. Maintainers review PRs as time permits.

What to expect:

Initial Review: Maintainer checks PR description and changes
Code Review: Detailed review of code quality and functionality
Feedback: You may receive requests for changes
Revisions: Make requested changes and push updates
Approval: Once approved, your PR will be merged

Responding to Feedback:

Be open to suggestions and constructive criticism
Ask questions if feedback is unclear
Make requested changes promptly
Update your PR branch as needed

Types of Contributions

Bug Fixes

Reporting Bugs

When reporting a bug, include:

Clear title: Summarize the issue
Description: Detailed explanation of the bug
Steps to reproduce: How to trigger the bug
Expected behavior: What should happen
Actual behavior: What actually happens
Environment: OS, Python version, MT5 version
Error messages: Complete error logs
Screenshots: If applicable

Use the GitHub issue template if available to ensure all necessary information is provided.

Fixing Bugs

When fixing a bug:

Reference the issue number in your PR
Explain the root cause
Describe your solution
Test thoroughly to ensure the fix works
Verify no new bugs are introduced

Example PR title: Fix: MT5 connection timeout issue (#42)

Feature Requests

Suggesting Features

Before suggesting a feature:

Check if it already exists
Search existing issues/PRs
Consider if it aligns with project goals
Think about implementation complexity

In your feature request:

Explain the problem it solves
Describe proposed solution
Provide use cases
Consider alternatives
Note any potential drawbacks

Implementing Features

Before implementing a major feature:

Discuss first: Open an issue to discuss the feature
Get feedback: Ensure maintainers agree it’s a good fit
Plan implementation: Outline your approach
Start development: Once approved, begin coding

Avoid spending significant time on a feature without first confirming it will be accepted.

Documentation Improvements

Documentation contributions are highly valued:

Fix typos and grammar errors
Clarify confusing sections
Add examples and tutorials
Improve formatting and structure
Translate documentation (if applicable)
Add diagrams or screenshots

Good documentation helps onboard new users and reduces support burden. Don’t underestimate its importance!

Community Guidelines

Code of Conduct

Be Respectful

Treat all contributors with respect
Welcome newcomers and help them learn
Accept constructive criticism gracefully
Focus on the issue, not the person
Respect different opinions and approaches

Be Professional

Use clear, professional language
Avoid offensive or inflammatory content
Stay on topic in discussions
Give credit where credit is due
Acknowledge your mistakes

Be Collaborative

Share knowledge and help others
Provide constructive feedback
Be open to learning from others
Work together to solve problems
Celebrate community successes

Communication Channels

GitHub Issues: Bug reports, feature requests
GitHub Discussions: Questions, ideas, general discussion
Pull Requests: Code contributions and reviews

When asking questions, provide context and show what you’ve tried. This helps others help you more effectively.

Recognition

Contributors

All contributors will be:

Listed in the project’s contributors page
Acknowledged in release notes (for significant contributions)
Credited in documentation (for documentation contributions)

We value all contributions, whether it’s fixing a typo or adding a major feature. Every contribution helps improve the project!

Advanced Topics

Adding New Indicators

When adding technical indicators:

Research: Ensure accurate implementation
Function: Create a clean, reusable function
Integration: Add to analysis pipeline
Dashboard: Update Streamlit UI if needed
AI: Update AI prompt to consider new indicator
Documentation: Explain the indicator and its use

Example structure:

def calculate_indicator(
    df: pd.DataFrame,
    **params
) -> pd.Series:
    """
    Calculate [Indicator Name].
    
    Args:
        df: OHLC DataFrame
        **params: Indicator parameters
        
    Returns:
        Series with indicator values
    """
    # Implementation
    pass

Platform Integrations

Interested in adding support for other platforms (TradingView, cTrader, etc.)?

Abstract data layer: Separate data fetching from analysis
Platform adapter: Create adapter for new platform
Configuration: Add platform selection option
Testing: Test thoroughly with the new platform
Documentation: Update docs with new platform setup

Platform integrations are complex. Please discuss with maintainers before starting significant work.

AI Model Improvements

Contributing to the AI component:

Improve prompt engineering
Add support for different LLM providers
Enhance context provided to AI
Improve signal formatting and clarity
Add confidence scoring

Questions?

Need help with contributing?

Check the FAQ
Review Troubleshooting
Search existing GitHub issues
Open a new discussion on GitHub

Don’t hesitate to ask questions! The community is here to help, and asking questions helps improve documentation for future contributors.

Thank You!

Thank you for contributing to the XAUUSD Trading Assistant AI! Your efforts help make this educational tool better for everyone.

Remember:

Start small if you’re new to contributing
Ask questions when needed
Be patient with the review process
Learn from feedback
Have fun and learn!

Happy coding! 🚀

Additional Resources

Welcome Contributors!

Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Submit Code

Getting Started

1. Fork and Clone the Repository

2. Set Up Development Environment

3. Create a Branch

Contribution Guidelines

Code Standards

Testing Requirements

Documentation Standards

Submitting Contributions

Pull Request Process

PR Review Process

Types of Contributions

Bug Fixes

Feature Requests

Documentation Improvements

Community Guidelines

Code of Conduct

Communication Channels

Recognition

Contributors

Advanced Topics

Adding New Indicators

Platform Integrations

AI Model Improvements

Questions?

Thank You!

Build docs developers (and LLMs) love

Additional Resources

​Welcome Contributors!

​Ways to Contribute

Report Bugs

Suggest Features

Improve Documentation

Submit Code

​Getting Started

​1. Fork and Clone the Repository

​2. Set Up Development Environment

​3. Create a Branch

​Contribution Guidelines

​Code Standards

​Testing Requirements

​Documentation Standards

​Submitting Contributions

​Pull Request Process

​PR Review Process

​Types of Contributions

​Bug Fixes

​Feature Requests

​Documentation Improvements

​Community Guidelines

​Code of Conduct

​Communication Channels

​Recognition

​Contributors

​Advanced Topics

​Adding New Indicators

​Platform Integrations

​AI Model Improvements

​Questions?

​Thank You!

Build docs developers (and LLMs) love

Welcome Contributors!

Ways to Contribute

Getting Started

1. Fork and Clone the Repository

2. Set Up Development Environment

3. Create a Branch

Contribution Guidelines

Code Standards

Testing Requirements

Documentation Standards

Submitting Contributions

Pull Request Process

PR Review Process

Types of Contributions

Bug Fixes

Feature Requests

Documentation Improvements

Community Guidelines

Code of Conduct

Communication Channels

Recognition

Contributors

Advanced Topics

Adding New Indicators

Platform Integrations

AI Model Improvements

Questions?

Thank You!