Contributing to Quantbot
🤝 Join the Quantbot Community
We welcome contributions from developers, traders, and financial professionals. Help us build the future of AI-powered financial analysis!
Ways to Contribute
Code
Features
Most Needed
Documentation
Guides
High Impact
Testing
Bug Reports
Always Welcome
Ideas
Features
Share Yours
Getting Started
1. Set Up Development Environment
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/Quantbot.git
cd Quantbot
# Backend setup
cd Quantbot-BE
make create_environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
make requirements
# Set up pre-commit hooks
pre-commit install
2. Development Workflow
# Create a feature branch
git checkout -b feature/your-feature-name
# Make your changes
# ... code, test, commit ...
# Run tests
uv run pytest --cov=app --cov-report=term-missing tests/
# Run linting and formatting
make lint
make format
# Push and create PR
git push origin feature/your-feature-name
Code Guidelines
Python Style Guide
We follow PEP 8 with some modifications:
Code Style Example
from typing import Dict, List, Optional
from decimal import Decimal
import logging
logger = logging.getLogger(__name__)
class PortfolioManager:
"""Manages portfolio operations and analysis.
This class provides methods for portfolio tracking,
performance analysis, and risk management.
"""
def __init__(self, api_key: str, environment: str = "paper") -> None:
self.api_key = api_key
self.environment = environment
self._positions: Dict[str, Position] = {}
def add_position(
self,
symbol: str,
quantity: int,
price: Decimal
) -> Optional[Position]:
"""Add a new position to the portfolio.
Args:
symbol: Stock symbol (e.g., 'AAPL')
quantity: Number of shares
price: Purchase price per share
Returns:
Position object if successful, None otherwise
Raises:
ValueError: If symbol is invalid
QuantbotError: If API call fails
"""
if not symbol or not symbol.isalpha():
raise ValueError(f"Invalid symbol: {symbol}")
try:
position = Position(symbol, quantity, price)
self._positions[symbol] = position
logger.info(f"Added position: {symbol} x{quantity} @ ${price}")
return position
except Exception as e:
logger.error(f"Failed to add position {symbol}: {e}")
return None
TypeScript/JavaScript Style
For frontend contributions:
TypeScript Style
interface PortfolioData {
totalValue: number;
positions: Position[];
performance: PerformanceMetrics;
}
class PortfolioService {
private apiClient: ApiClient;
constructor(apiKey: string) {
this.apiClient = new ApiClient(apiKey);
}
async getPortfolio(): Promise<PortfolioData> {
try {
const response = await this.apiClient.get('/portfolio');
return response.data;
} catch (error) {
console.error('Failed to fetch portfolio:', error);
throw new PortfolioError('Unable to load portfolio data');
}
}
}
Testing Guidelines
Writing Tests
Test Example
import pytest
from decimal import Decimal
from quantbot.portfolio import PortfolioManager
from quantbot.exceptions import QuantbotError
class TestPortfolioManager:
"""Test suite for PortfolioManager class."""
@pytest.fixture
def portfolio_manager(self):
"""Create a test portfolio manager."""
return PortfolioManager(api_key="test_key", environment="test")
def test_add_position_success(self, portfolio_manager):
"""Test successful position addition."""
position = portfolio_manager.add_position("AAPL", 100, Decimal("150.00"))
assert position is not None
assert position.symbol == "AAPL"
assert position.quantity == 100
assert position.price == Decimal("150.00")
def test_add_position_invalid_symbol(self, portfolio_manager):
"""Test position addition with invalid symbol."""
with pytest.raises(ValueError, match="Invalid symbol"):
portfolio_manager.add_position("123", 100, Decimal("150.00"))
@pytest.mark.asyncio
async def test_portfolio_api_integration(self, portfolio_manager):
"""Test integration with portfolio API."""
# Mock API response
with patch('quantbot.api.client.ApiClient.get') as mock_get:
mock_get.return_value = {"total_value": 50000}
result = await portfolio_manager.get_portfolio_value()
assert result == 50000
Test Coverage
We aim for 90%+ test coverage:
# Run tests with coverage
uv run pytest --cov=app --cov-report=html tests/
# View coverage report
open htmlcov/index.html
Documentation
Writing Documentation
- Use clear, concise language
- Include code examples
- Add type hints and docstrings
- Update API documentation for changes
Documentation Example
def calculate_sharpe_ratio(
returns: List[float],
risk_free_rate: float = 0.02
) -> float:
"""Calculate the Sharpe ratio for a series of returns.
The Sharpe ratio measures risk-adjusted return by comparing
the excess return to the standard deviation of returns.
Args:
returns: List of periodic returns (e.g., daily, monthly)
risk_free_rate: Annual risk-free rate (default: 2%)
Returns:
Sharpe ratio as a float
Example:
>>> returns = [0.01, 0.02, -0.01, 0.03]
>>> sharpe = calculate_sharpe_ratio(returns)
>>> print(f"Sharpe ratio: {sharpe:.2f}")
Sharpe ratio: 1.23
Note:
Returns should be in decimal format (0.01 = 1%).
Risk-free rate is automatically adjusted for the return period.
"""
# Implementation here...
Feature Requests
Proposing New Features
Feature Request Template
GitHub Issue
Use our template for feature requests
Structured
Feature Request Template
## Feature Request: [Brief Description]
### Problem Statement
What problem does this feature solve? Who would benefit?
### Proposed Solution
Describe your proposed solution in detail.
### Alternative Solutions
What other approaches have you considered?
### Implementation Details
- API changes needed
- UI/UX considerations
- Performance implications
- Security considerations
### Success Criteria
How will we know this feature is successful?
### Priority
- [ ] Critical (blocking users)
- [ ] High (significant improvement)
- [ ] Medium (nice to have)
- [ ] Low (future consideration)
Bug Reports
Reporting Bugs
ISSUE
GitHub Issues
Report bugs using our structured template for faster resolution.
Bug Report Template
Paste any error messages or logs here
## Bug Report: [Brief Description]
### Environment
- Quantbot Version:
- Python Version:
- Operating System:
- Browser (if applicable):
### Steps to Reproduce
1. Step one
2. Step two
3. Step three
### Expected Behavior
What should have happened?
### Actual Behavior
What actually happened?
### Error Messages
### Screenshots
If applicable, add screenshots to help explain the problem.
### Additional Context
Any other context about the problem.
Community Guidelines
Code of Conduct
We are committed to providing a welcoming and inclusive environment:
- Be respectful - Treat everyone with respect and kindness
- Be collaborative - Work together towards common goals
- Be inclusive - Welcome newcomers and diverse perspectives
- Be constructive - Provide helpful feedback and suggestions
- Be patient - Remember that everyone is learning
Communication Channels
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - General questions and ideas
- Discord - Real-time chat and community support
- Email - Direct contact for sensitive issues
Getting Help
Development Support
- Documentation - Check existing docs first
- GitHub Discussions - Ask questions publicly
- GitHub Issues - Report bugs or request features
- Code Review - Request reviews on PRs
Ready to Contribute? 🚀
Join our community of developers building the future of financial AI.
View on GitHub