贡献指南¶
欢迎参与 EasyQuant:bug 报告、功能建议、文档改进、代码贡献都可以。
贡献方式¶
报告 Bug¶
到 GitHub Issues 提交,请带上:
- 问题描述
- 复现步骤(能给最小示例最好)
- 期望行为 vs 实际行为
- Python 版本与
eqlib版本 - 相关日志或报错信息
提功能建议¶
先开 Issue 讨论,再提 PR。提前对齐范围和设计,免得白写。
提交 Pull Request¶
- Fork 仓库,建功能分支(
git checkout -b feature/my-feature) - 改代码——沿用现有代码风格
- 代码改动要在
tests/里补或更新测试 - 跑测试:
python -m pytest tests/ - 提交信息用约定前缀(见下文)
- 推送并向
main提 PR
开发环境¶
代码风格¶
- 遵循 PEP 8,写类型标注
- 导入要显式——示例里不要
from eqlib import * - 公开 API 函数写 docstring
eqlib/__init__.py的导出标注STABLE/EXPERIMENTAL/DEPRECATED- 用
eqlib/constants.py里的共享常量(RISK_FREE_RATE = 0.03、TRADING_DAYS_PER_YEAR = 244),不要硬编码 - Pre-commit 钩子会检查行尾空白、文件末尾换行、YAML/TOML 语法
文档¶
文档在 docs/,中英双语:每个 *.md 都有一个对应的 *.en.md。
- 改
docs/**/*.md时,同一个 PR 里同步更新对应的.en.md - 提交前跑
python scripts/check_doc_sync.py——它检查翻译配对、失效的示例引用、交易成本数字是否与examples/_defaults.py一致 - CI 跑
mkdocs build --strict;本地可用mkdocs serve预览 - 改
eqlib/公开 API 时,要连带更新受影响的示例、教程(双语)和docs/reference/
示例¶
在 examples/ 下新增或修改示例时:
- 交易成本与股票代码统一用
examples/_defaults.py(印花税 0.05%、佣金 0.025%、最低 5 元) - 模块 docstring 写清编号、标题、说明、教学目标
- 加
if __name__ == "__main__":守卫 - 两个索引都要更新:
examples/README.md和docs/examples/index.md(含.en.md)
提交信息¶
用约定前缀:
| 前缀 | 用途 |
|---|---|
docs: |
文档(永远同时更新 .md 和 .en.md) |
fix: |
Bug 修复 |
feat: |
新功能或新示例 |
chore: |
清理、重组 |
refactor: |
不改变行为的重构 |
许可证¶
贡献即表示你同意所提交内容以 MIT License 发布。