Contributing Guidelines¶

Overview¶

Thank you for your interest in contributing to BestTradingBot! This document provides guidelines and instructions for contributing to the project. We appreciate all contributions, whether they're bug reports, feature requests, documentation improvements, or code changes.

Code of Conduct¶

Please read and follow our Code of Conduct to keep our community respectful and inclusive.

Getting Started¶

Prerequisites¶

Python 3.10 or higher
Git
Basic understanding of PyTorch, trading systems, and machine learning

Setting Up Development Environment¶

Fork the repository
Clone your fork locally:

git clone https://github.com/yourusername/btb-besttradingbot.git
cd btb-besttradingbot

Set up a virtual environment:

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

Install development dependencies:

pip install -e ".[dev]"
pip install -r requirements.txt

Set up pre-commit hooks:

pre-commit install

Development Process¶

Branching Strategy¶

We follow a simplified Git flow model:

main: Stable release branch
develop: Active development branch
Feature branches: Created from develop for specific features or fixes

Name your feature branches following this convention: feature/descriptive-name or fix/issue-description.

Pull Request Process¶

Create a branch from develop for your feature or fix
Make your changes, following our coding standards
Add or update tests to cover your changes
Update documentation if necessary
Run tests and static analysis to ensure everything passes
Submit a pull request to the develop branch
Address any feedback during code review
Once approved, your PR will be merged

Coding Standards¶

Style Guide¶

We follow PEP 8 with a few exceptions:

Line length: 100 characters maximum
Import order: standard library, third-party packages, local modules

We use a combination of Black, isort, and ruff for code formatting and linting.

Docstrings¶

We use Google-style docstrings for all public functions, classes, and methods:

def function_with_types_in_docstring(param1: int, param2: str) -> bool:
    """Example function with types documented in the docstring.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
        The return value. True for success, False otherwise.

    Raises:
        ValueError: If param1 is less than 0.
    """
    if param1 < 0:
        raise ValueError("param1 must be >= 0")
    return param1 > 0

Type Hints¶

We use Python type hints for all function arguments and return values:

from typing import Dict, List, Optional, Tuple, Union

def process_data(data: pd.DataFrame, config: Dict[str, Any]) -> Tuple[pd.DataFrame, Dict[str, float]]:
    # Implementation
    return processed_data, metrics

Testing¶

Writing Tests¶

We use pytest for our testing framework. All tests should be placed in the tests/ directory, following the same structure as the module they test.

Each test file should start with test_ and each test function should also start with test_.

# tests/models/test_transformer.py
import pytest
import torch
from btb.models.transformer import TransformerModel

def test_transformer_initialization():
    config = {
        "input_dim": 10,
        "hidden_dim": 64,
        "output_dim": 2,
        "num_layers": 3,
        "nhead": 8
    }
    model = TransformerModel(config)
    assert isinstance(model, TransformerModel)
    # More assertions...

def test_transformer_forward_pass():
    # Test the forward pass logic
    # ...

Running Tests¶

To run the tests:

pytest

To run tests with coverage:

pytest --cov=btb tests/

Documentation¶

Writing Documentation¶

We use Markdown for documentation. All documentation files should be placed in the docs/ directory.

When adding new features, please update relevant documentation files or create new ones if needed. Documentation should be clear, concise, and include examples when appropriate.

Building Documentation¶

To build the documentation locally:

mkdocs build

To serve the documentation site locally for preview:

mkdocs serve

Submitting Changes¶

Issue Tracking¶

Before starting work on a new feature or fix, check the issue tracker to see if it's already being discussed. If not, create a new issue to discuss the proposed changes before investing significant time in implementation.

Pull Requests¶

When submitting a pull request:

Reference any related issues in the PR description
Provide a clear description of the changes made
Include any necessary testing instructions
Update relevant documentation
Ensure all CI checks pass

Release Process¶

Our release process follows these steps:

Feature freeze on develop branch
Comprehensive testing and bug fixing
Version bump according to Semantic Versioning
Release candidate testing
Merge to main branch
Tag release with version number
Build and publish package

Additional Resources¶

Recognition¶

All contributors will be recognized in our CONTRIBUTORS.md file. We value and appreciate your contributions to making BestTradingBot better!

Questions and Support¶

If you have questions or need support with contributing, please:

Open an issue with the "question" label
Join our Discord community
Contact the maintainers directly

Thank you for contributing to BestTradingBot!