Contributing

We welcome contributions to qfinbox! This document provides guidelines for contributing to the project.

Getting Started

Fork the Repository

Fork the qfinbox repository on GitHub and clone your fork locally:
```
git clone https://github.com/yourusername/qfinbox.git
cd qfinbox
```
Set Up Development Environment

Install the development dependencies:
```
pip install -e .[dev]
```

Create a Feature Branch

git checkout -b feature/your-feature-name

Development Guidelines

Code Style

We use several tools to maintain code quality:

Black for code formatting
isort for import sorting
flake8 for linting
mypy for type checking

Run these tools before submitting:

# Format code
black src/ tests/
isort src/ tests/

# Check linting
flake8 src/ tests/

# Type checking
mypy src/

Or use pre-commit hooks:

pre-commit install
pre-commit run --all-files

Testing

Write tests for all new functionality:

# Run tests
pytest tests/

# With coverage
pytest tests/ --cov=qfinbox --cov-report=html

Documentation

Update documentation for new features:

Add docstrings to all public functions and classes
Follow NumPy/Google docstring style
Update relevant .rst files in docs/
Add examples for complex functionality

Commit Guidelines

Use clear, descriptive commit messages:

feat: add portfolio optimization module
fix: resolve numerical instability in VaR calculation
docs: update risk management examples
test: add tests for Monte Carlo simulation

Types of Contributions

Bug Reports

When reporting bugs, please include:

Clear description of the issue
Minimal code example to reproduce
Expected vs actual behavior
Python version and dependencies
Error messages and stack traces

Feature Requests

For new features, please:

Describe the use case and motivation
Provide examples of the proposed API
Consider performance implications
Check if similar functionality exists

Code Contributions

We welcome contributions in these areas:

Risk Management * New risk metrics and models * Stress testing frameworks * Regulatory capital calculations

Portfolio Optimization * Alternative optimization algorithms * Multi-objective optimization * Transaction cost modeling

Financial Models * Options pricing models * Fixed income analytics * Credit risk models

Data Integration * New data source connectors * Data cleaning utilities * Market data normalization

Performance * Algorithmic improvements * Caching mechanisms * Parallel processing

Code Review Process

Submit Pull Request

Create a pull request with:
- Clear title and description
- Link to related issues
- Summary of changes made
- Testing performed
Code Review

Maintainers will review for:
- Code quality and style
- Test coverage
- Documentation completeness
- Performance considerations
- API design consistency
Continuous Integration

All PRs must pass:
- Unit tests
- Code quality checks
- Documentation builds
- Example notebook execution

Documentation Standards

Docstring Format

Use NumPy-style docstrings:

def calculate_var(returns: np.ndarray, confidence: float = 0.95) -> float:
    """Calculate Value at Risk using historical method.

    Parameters
    ----------
    returns : np.ndarray
        Array of historical returns
    confidence : float, default 0.95
        Confidence level for VaR calculation

    Returns
    -------
    float
        Value at Risk at specified confidence level

    Examples
    --------
    >>> returns = np.random.normal(0, 0.01, 1000)
    >>> var_95 = calculate_var(returns, 0.95)
    >>> print(f"95% VaR: {var_95:.4f}")
    95% VaR: -0.0163

    Notes
    -----
    This implementation uses the historical simulation method,
    which makes no assumptions about return distribution.

    References
    ----------
    .. [1] Jorion, P. (2007). Value at Risk: The New Benchmark
           for Managing Financial Risk. McGraw-Hill.
    """

Example Guidelines

When adding examples:

Use realistic but synthetic data
Include full working code
Add explanatory comments
Show visualization when appropriate
Provide interpretation of results

Release Process

qfinbox follows semantic versioning (SemVer):

Major (x.0.0): Breaking API changes
Minor (x.y.0): New features, backward compatible
Patch (x.y.z): Bug fixes, backward compatible

Community Guidelines

Be respectful and inclusive
Help newcomers get started
Share knowledge and expertise
Provide constructive feedback
Follow the code of conduct

Getting Help

If you need help:

Check existing documentation and examples
Search GitHub issues for similar problems
Ask questions in GitHub Discussions
Contact maintainers directly for urgent issues

Recognition

Contributors are recognized through:

GitHub contributor list
Release notes acknowledgments
Documentation credits
Conference presentations (with permission)

Thank You!

Thank you for contributing to qfinbox! Your efforts help make quantitative finance more accessible to the Python community.