🇨🇳 简体中文
🇺🇸 English
🇯🇵 日本語

贡献指南

欢迎为 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"

提交类型：

5. 创建 Pull Request

  1. 推送分支: git push origin feature/your-feature
  2. 访问 GitHub 创建 PR
  3. 填写 PR 模板
  4. 等待代码审查

📝 PR 模板

## 变更说明
简要描述此 PR 的目的

## 变更类型
- [ ] 新功能
- [ ] Bug 修复
- [ ] 文档更新
- [ ] 重构
- [ ] 其他

## 变更详情
- 具体改动点 1
- 具体改动点 2

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试通过

## 文档
- [ ] 更新了相关文档
- [ ] 更新了 API 文档（如有变更）

## Breaking Changes
- [ ] 此 PR 包含破坏性变更

✅ 代码审查标准

必须满足

质量要求

测试覆盖

📋 文档维护标准

文档更新核心原则

  1. 真实性原则: 文档必须反映当前代码的实际状态，不描述未实现的功能
  2. 直接更新原则: 直接修改文档内容，而非打补丁方式
  3. 职责明确原则: 每个文档有明确的职责范围，不越界
  4. 简洁务实原则: 不使用营销语言，不空谈特性和优势
  5. 链接有效原则: 所有文档内链接必须有效且可访问

文档职责范围

文档 职责 内容要求
docs/api/ API接口文档 自动生成，无需手动更新
docs/architecture/ 系统架构设计 包含具体的技术架构、模块设计、数据流、技术选型等
docs/domain/ 领域模型定义 数据模型、业务实体、领域概念、业务规则
docs/strategies/ 策略文档 策略算法说明、参数定义、使用示例、性能指标
docs/cli.md 命令行使用指南 CLI命令、参数、示例、常见问题
docs/development.md 开发环境配置 环境搭建、依赖安装、配置说明、调试方法
docs/index.md 项目总览 项目简介、快速开始、目录结构、链接索引
docs/contributing.md 贡献指南 贡献流程、代码规范、提交规范、文档标准

何时必须更新文档

架构文档 (architecture/)

领域文档 (domain/)

策略文档 (strategies/)

开发文档 (development.md)

CLI文档 (cli.md)

文档编写规范

1. 格式规范

# 一级标题（文档标题）

## 二级标题（主要章节）

### 三级标题（子章节）

**重要内容使用加粗**

`行内代码使用反引号`

​```python
# 代码块必须指定语言
def example():
    """代码示例必须可运行"""
    pass
​```

| 列标题 | 说明 |
|--------|------|
| 数据 | 描述 |

2. 内容规范

架构文档示例

## 模块名称

### 职责
- 具体职责描述（非空谈）

### 接口
- 提供的接口列表
- 参数和返回值说明

### 依赖
- 依赖的其他模块
- 外部库依赖

### 实现
- 核心算法或流程（伪代码或流程图）

策略文档示例

## 策略名称

### 算法原理
- 数学公式或逻辑说明

### 参数定义

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| period | int | 14 | 计算周期 |

### 使用示例
​```python
strategy = RSIStrategy(period=14)
​```

### 性能指标
- 计算复杂度: O(n)
- 内存占用: O(1)
- 历史回测结果（如有）

3. 禁止事项

❌ 不要在架构文档中：

❌ 不要在策略文档中：

❌ 不要在任何文档中：

文档审查清单

提交前检查：

🐛 报告问题

Bug 报告

创建 Issue 并提供：

  1. 问题描述
  2. 复现步骤
  3. 期望行为
  4. 实际行为
  5. 环境信息（OS、Python版本等）
  6. 相关日志

功能请求

创建 Issue 并说明：

  1. 功能描述
  2. 使用场景
  3. 预期收益
  4. 可能的实现方案

💬 沟通方式

🎯 开发原则

  1. 代码质量优于速度: 宁可慢一点，也要保证质量
  2. 测试驱动: 先写测试，再写代码
  3. 文档同步: 代码变更必须同步文档
  4. 向后兼容: 尽量避免破坏性变更
  5. 安全第一: 不引入安全漏洞

🚀 CI/CD 与持续集成

GitHub Actions 配置

Fire 项目使用 GitHub Actions 进行自动化测试、构建和文档部署。

初始配置步骤

1. 配置 GitHub Pages

  1. 打开 GitHub 仓库 → Settings → Pages
  2. Source 选择：GitHub Actions
  3. 自动保存

2. 配置工作流权限

  1. Settings → Actions → General
  2. 滚动到 Workflow permissions
  3. 选择：Read and write permissions
  4. 勾选：Allow GitHub Actions to create and approve pull requests
  5. 点击 Save

3. 触发构建 推送代码到 main 或 develop 分支即可自动触发，或手动触发：

  1. Actions 标签页
  2. 选择 CI/CD Pipeline
  3. 点击 Run workflow
  4. 选择分支并运行

4. 访问文档 等待构建完成（3-5 分钟），然后访问：https://用户名.github.io/仓库名/

工作流说明

CI/CD 工作流包含 5 个任务：

  1. Backend (2-3分钟) - 后端测试和覆盖率
  2. Frontend (1-2分钟) - 前端检查和构建
  3. Generate Docs (1分钟) - 生成文档和更新徽章
  4. Deploy Docs (2-3分钟) - 部署到 GitHub Pages
  5. Update Badges (30秒) - 提交徽章更新

总计: 约 5-10 分钟

验证清单

构建完成后验证：

常见问题

Q: 工作流失败？

Q: Pages 部署失败？

Q: 如何跳过 CI？

git commit -m "docs: 更新文档 [skip ci]"

CI/CD 最佳实践

  1. 保持测试覆盖率 ≥80%
  2. 使用语义化提交信息 
    feat: 添加新功能
fix: 修复问题
docs: 更新文档
  3. 本地先测试再推送 
    ./scripts/test.sh unit
./scripts/lint-fix.sh

🔗 相关资源