贡献指南
欢迎为 Fire 项目贡献代码！请遵循以下流程和规范。
🚀 贡献流程
1. Fork 项目
# Fork 到你的 GitHub 账号
# Clone 到本地
git clone https://github.com/YOUR_USERNAME/fire.git
cd fire
# 添加上游仓库
git remote add upstream https://github.com/ORIGINAL_OWNER/fire.git
2. 创建分支
# 同步上游代码
git fetch upstream
git checkout main
git merge upstream/main
# 创建功能分支
git checkout -b feature/your-feature
# 或修复分支
git checkout -b fix/bug-description
3. 开发和测试
# 开发前先运行测试确保环境正常
./scripts/test.sh all
# 开发完成后运行测试
./scripts/test.sh unit
./scripts/test.sh integration
# 代码格式化
./scripts/lint-fix.sh
4. 提交代码
# 提交规范
git add .
git commit -m "type: description
- Detail 1
- Detail 2"
提交类型：
feat: 新功能fix: 修复 bugdocs: 文档更新style: 代码格式refactor: 重构test: 测试相关chore: 构建/工具
5. 创建 Pull Request
- 推送分支:
git push origin feature/your-feature - 访问 GitHub 创建 PR
- 填写 PR 模板
- 等待代码审查
📝 PR 模板
## 变更说明
简要描述此 PR 的目的
## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他
## 变更详情
- 具体改动点 1
- 具体改动点 2
## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过
## 文档
- [ ] 更新了相关文档
- [ ] 更新了 API 文档（如有变更）
## Breaking Changes
- [ ] 此 PR 包含破坏性变更
✅ 代码审查标准
必须满足
- ✅ 所有测试通过
- ✅ 代码符合规范
- ✅ 文档已更新
- ✅ 无安全问题
质量要求
- 代码清晰易懂
- 有适当的注释
- 无重复代码
- 错误处理完善
测试覆盖
- 整体覆盖率 ≥ 85%
- 策略模块 ≥ 90%
- 核心交易引擎 ≥ 85%
- API 端点 ≥ 70%
- 集成测试覆盖所有关键路径
📋 文档维护标准
文档维护需遵循统一的规范和标准流程，详见：
文档更新要点
- 何时更新: 架构变更、领域模型变更、策略变更、开发实践变更、API 变更时必须更新相应文档
- 如何更新: 使用
/archive-spec命令自动更新，再手动补充复杂内容 - 质量检查: 无未来语言、无禁止词汇、Markdown 语法正确、链接有效
# 验证文档质量
grep -rn "将要\|计划\|未来" docs/architecture/
grep -rn "高性能\|灵活\|鲁棒" docs/architecture/
🐛 报告问题
Bug 报告
创建 Issue 并提供：
- 问题描述
- 复现步骤
- 期望行为
- 实际行为
- 环境信息（OS、Python版本等）
- 相关日志
功能请求
创建 Issue 并说明：
- 功能描述
- 使用场景
- 预期收益
- 可能的实现方案
💬 沟通方式
- Issue: 技术讨论和问题报告
- PR: 代码审查和技术细节
- Email: 私密或紧急事项
🎯 开发原则
- 代码质量优于速度: 宁可慢一点，也要保证质量
- 测试驱动: 先写测试，再写代码
- 文档同步: 代码变更必须同步文档
- 向后兼容: 尽量避免破坏性变更
- 安全第一: 不引入安全漏洞
🚀 CI/CD 与持续集成
GitHub Actions 配置
Fire 项目使用 GitHub Actions 进行自动化测试、构建和文档部署。
初始配置步骤
1. 配置 GitHub Pages
- 打开 GitHub 仓库 → Settings → Pages
- Source 选择：GitHub Actions
- 自动保存
2. 配置工作流权限
- Settings → Actions → General
- 滚动到 Workflow permissions
- 选择：Read and write permissions
- 勾选：Allow GitHub Actions to create and approve pull requests
- 点击 Save
3. 触发构建 推送代码到 main 或 develop 分支即可自动触发，或手动触发：
- Actions 标签页
- 选择 CI/CD Pipeline
- 点击 Run workflow
- 选择分支并运行
4. 访问文档
等待构建完成（3-5 分钟），然后访问：https://用户名.github.io/仓库名/
工作流说明
CI/CD 工作流包含 5 个任务：
- Backend (2-3分钟) - 后端测试和覆盖率
- Frontend (1-2分钟) - 前端检查和构建
- Generate Docs (1分钟) - 生成文档和更新徽章
- Deploy Docs (2-3分钟) - 部署到 GitHub Pages
- Update Badges (30秒) - 提交徽章更新
总计: 约 5-10 分钟
验证清单
构建完成后验证：
- Actions 显示工作流运行成功
- README 的 CI/CD 徽章显示”passing”
- Coverage 徽章显示覆盖率百分比
- 文档站点可访问
- 语言切换器正常工作
- Mermaid 图表正确显示
常见问题
Q: 工作流失败？
- 检查 Workflow permissions 配置
- 查看失败任务的详细日志
- 确保依赖文件正确
Q: Pages 部署失败？
- 确认 Source 设置为 GitHub Actions
- 检查工作流权限
- 查看 Deploy Docs 日志
Q: 如何跳过 CI？
git commit -m "docs: 更新文档 [skip ci]"
CI/CD 最佳实践
- 保持测试覆盖率 ≥80%
- 使用语义化提交信息
feat: 添加新功能 fix: 修复问题 docs: 更新文档 - 本地先测试再推送
./scripts/test.sh unit ./scripts/lint-fix.sh