贡献指南

感谢您花时间参与贡献。没有任何贡献是微不足道的，无论是文档中的拼写错误，还是贡献代码和参与数据标准化，我们都感谢您的每一份努力。

我们希望您的贡献体验是愉快的，如果有任何我们可以改进的地方，请向我们发送反馈。下面的列表旨在为一般期望提供一些指导。

1. 用例

确保您的贡献直接增强 OpenBB 平台的功能或扩展生态系统。
贡献应该解决实际问题或添加有价值的功能。
考虑贡献对用户体验的影响。

2. 文档

所有代码贡献都应该附带相关文档，包括贡献的目的、工作原理以及对现有功能的任何更改。
如果您的贡献改变了 OpenBB 平台的行为，请更新任何现有文档。
新的路由器函数必须定义使用示例。

文档要求

def new_function(symbol: str, provider: str = "default") -> dict:
    """
    获取股票数据的新函数
    
    参数
    ----------
    symbol : str
        股票代码
    provider : str, 可选
        数据提供商，默认为 "default"
    
    返回
    -------
    dict
        包含股票数据的字典
    
    示例
    --------
    >>> data = new_function("AAPL", provider="yfinance")
    >>> print(data)
    """
    pass

3. 代码质量

您的代码应严格遵守 OpenBB 平台的编码标准和约定。
确保代码的清晰性、可维护性和适当的组织结构。

编码标准

# 好的示例
class StockDataFetcher:
    """股票数据获取器类"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self._session = None
    
    def fetch_data(self, symbol: str) -> dict:
        """获取股票数据"""
        if not symbol:
            raise ValueError("股票代码不能为空")
        
        # 实现数据获取逻辑
        return self._make_request(symbol)
    
    def _make_request(self, symbol: str) -> dict:
        """私有方法：发起 API 请求"""
        # 实现请求逻辑
        pass

代码审查清单

4. 测试

所有贡献都必须经过彻底测试，以避免向 OpenBB 平台引入错误。
贡献应包括相关的自动化测试（单元测试和集成测试），任何新功能都应该附带其测试用例。
有关测试和 QA 基础设施的详细信息，请参阅测试页面。

测试示例

import pytest
from unittest.mock import Mock, patch

class TestStockDataFetcher:
    """股票数据获取器测试类"""
    
    def setup_method(self):
        """测试设置"""
        self.fetcher = StockDataFetcher("test_api_key")
    
    def test_fetch_data_success(self):
        """测试成功获取数据"""
        with patch.object(self.fetcher, '_make_request') as mock_request:
            mock_request.return_value = {"symbol": "AAPL", "price": 150.0}
            
            result = self.fetcher.fetch_data("AAPL")
            
            assert result["symbol"] == "AAPL"
            assert result["price"] == 150.0
            mock_request.assert_called_once_with("AAPL")
    
    def test_fetch_data_empty_symbol(self):
        """测试空股票代码的错误处理"""
        with pytest.raises(ValueError, match="股票代码不能为空"):
            self.fetcher.fetch_data("")
    
    @pytest.mark.integration
    def test_fetch_data_integration(self):
        """集成测试"""
        # 实际 API 调用测试
        pass

5. 性能

您的贡献应该针对性能进行优化，不应降低 OpenBB 平台的整体效率。
解决任何潜在的瓶颈并确保可扩展性。

性能最佳实践

# 使用生成器而不是列表（内存效率）
def process_large_dataset(data):
    for item in data:
        yield process_item(item)

# 缓存昂贵的计算
from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_calculation(param):
    # 昂贵的计算
    return result

# 异步处理多个请求
import asyncio

async def fetch_multiple_stocks(symbols):
    tasks = [fetch_stock_data(symbol) for symbol in symbols]
    return await asyncio.gather(*tasks)

6. 协作

与 OpenBB 团队和社区积极协作。
参与代码审查过程。
响应反馈并进行必要的修改。

贡献流程

Fork 仓库

git clone https://github.com/your-username/OpenBBTerminal.git
cd OpenBBTerminal

创建功能分支

git checkout -b feature/your-feature-name

进行更改
- 编写代码
- 添加测试
- 更新文档
运行测试
```
pytest tests/
```

提交更改

git add .
git commit -m "feat: 添加新的股票数据获取功能"

推送并创建 Pull Request

git push origin feature/your-feature-name

7. 提交消息规范

使用约定式提交格式：

<类型>[可选范围]: <描述>

[可选正文]

[可选脚注]

提交类型

feat: 新功能
fix: 错误修复
docs: 文档更改
style: 代码格式更改
refactor: 代码重构
test: 添加或修改测试
chore: 构建过程或辅助工具的变动

示例

feat(equity): 添加新的股票价格获取端点

添加了支持实时股票价格获取的新端点，包括：
- 实时价格数据
- 历史价格数据
- 多个数据提供商支持

Closes #123

8. 代码审查

审查者指南

检查代码质量和一致性
验证测试覆盖率
确认文档完整性
评估性能影响

贡献者指南

响应审查反馈
进行必要的修改
保持讨论的建设性
学习和改进

9. 社区参与

参与 GitHub 讨论
帮助回答问题
报告和修复错误
提出改进建议

10. 资源

感谢您对 OpenBB 平台的贡献！您的努力帮助我们构建更好的开源金融数据平台。

1. 用例​

2. 文档​

文档要求​

3. 代码质量​

编码标准​

代码审查清单​

4. 测试​

测试示例​

5. 性能​

性能最佳实践​

6. 协作​

贡献流程​

7. 提交消息规范​

提交类型​

示例​

8. 代码审查​

审查者指南​

贡献者指南​

9. 社区参与​

10. 资源​