Pysystemtrade项目开发协作指南：从分支管理到代码规范

Pysystemtrade项目开发协作指南：从分支管理到代码规范

项目概述

Pysystemtrade是一个基于Python的系统化交易框架，为量化交易策略的开发、测试和执行提供完整解决方案。作为开源项目，它遵循特定的开发流程和代码规范，确保项目质量和协作效率。

开发环境配置

基础环境搭建

1. 创建本地开发副本：

git clone <你的项目副本地址>
cd pysystemtrade

2. 设置上游仓库关联：

git remote add upstream <主项目仓库地址>

这一步骤确保你的本地开发环境能够与主项目保持同步。

环境更新机制

定期执行以下命令保持开发分支同步：

git checkout develop
git pull

分支管理策略

核心分支结构

项目采用经典的分支模型，包含两个主要分支：

1. master分支：稳定版本发布分支
2. develop分支：日常开发集成分支

功能开发分支规范

开发新功能或修复问题时，应遵循以下分支规范：

1. 从develop分支创建新分支：

git checkout -b feature-<问题编号>-简短描述

2. 分支命名约定：

   • 功能开发：feature-<编号>-描述
   • 问题修复：bug-<编号>-描述

3. 开发完成后推送至个人远程仓库：

git push origin 分支名称

代码提交流程

提交前检查

1. 检查变更状态：

git status
git diff

2. 添加并提交变更：

git add --all
git commit

同步上游变更

在提交合并请求前，应先合并上游最新变更：

git fetch upstream
git merge upstream/develop 你的分支名

代码质量保障

单元测试规范

项目采用pytest测试框架，测试执行方式：

1. 运行全部测试：

pytest

2. 运行指定模块测试：

pytest sysdata/tests/test_config.py

3. 跳过耗时测试（默认跳过标记为@pytest.mark.slow的测试）：

pytest --ignore=慢速测试模块路径

4. 包含耗时测试：

pytest --runslow

代码格式化标准

项目采用Black代码格式化工具，使用规范：

1. 全局格式化：

black .

2. 排除虚拟环境：

black . --exclude '/.venv\/.+/'

建议配置IDE实现保存时自动格式化，确保代码风格统一。

代码开发规范

通用编码原则

1. 参数传递应显式声明，避免隐式参数
2. 默认参数建议使用arg_not_supplied占位符
3. 必须使用类型注解(Type Hints)
4. 避免冗长的文档字符串，优先使用类型注解说明

命名约定

1. 类命名采用混合大小写(CamelCase)
2. 常用方法命名规范：
   • 获取数据：get
   • 计算操作：calculate
   • 数据读取：read
   • 数据写入：write
3. 数据层级对象需遵循特定命名规则

异常处理规范

1. 生产环境代码应避免抛出不可恢复的异常
2. 关键错误必须记录日志(log.critical)

文档维护

文档更新后需同步目录结构，使用专用脚本生成：

./docs/gh-md-toc --insert --no-backup --hide-footer docs/文档名称.md

最佳实践建议

1. 小型变更可直接提交合并请求
2. 重大功能修改应先发起讨论方案
3. 提交信息应清晰描述变更内容
4. 定期同步上游变更避免冲突
5. 开发前确认现有测试覆盖率

通过遵循这些规范，开发者可以高效地参与项目贡献，同时确保代码质量和项目一致性。