Contributing Guide

贡献指南

欢迎为 FastQTools 做贡献！本页面介绍 Git 提交规范、开发流程和代码审查要求。

---

开发环境搭建

详见 Getting Started 和 DevContainer and Docker。

# 克隆仓库
git clone git@github.com:LessUp/fastq-tools.git
cd fastq-tools

# 安装依赖
./scripts/core/install-deps

# 构建
./scripts/core/build

# 测试
./scripts/core/test

---

Git 提交规范

提交格式

<type>(<scope>): <subject>

Type 类型

类型	描述
feat	新功能
fix	Bug 修复
docs	文档更改
style	代码风格（不影响功能）
refactor	代码重构
perf	性能优化
test	添加或修改测试
build	构建系统或依赖更改
ci	CI/CD 配置更改
chore	其他维护性更改

Scope 范围（可选）

• core: 核心功能
• cli: 命令行接口
• parser: 解析器
• io: I/O 模块
• devops: 运维相关
• docs: 文档相关

Subject 规则

• 使用祈使句，现在时态
• 第一个字母不要大写
• 结尾不加句号

示例

feat(parser): add BAM file input support
fix(core): correct GC content calculation
docs(readme): update installation instructions
refactor(pipeline): simplify processing loop
perf(io): optimize buffer allocation
ci(github): add automated linting

提交信息模板

# 启用仓库内模板
git config commit.template .gitmessage.txt
# Dev Container 会自动设置该配置

---

开发流程

1. 创建功能分支

git checkout -b feat/my-feature

2. 开发与测试

# 编码...

# 格式化
./scripts/core/lint format

# 测试
./scripts/core/test

# 检查代码质量
./scripts/core/lint all

3. 提交

git add .
git commit  # 遵循提交规范

4. 推送与 PR

git push origin feat/my-feature
# 在 GitHub 创建 Pull Request

---

代码审查清单

功能

• 代码实现了预期功能
• 边界情况已处理
• 错误处理完善

质量

• 代码格式化通过 (./scripts/core/lint check)
• 静态分析通过 (./scripts/core/lint tidy)
• 无编译器警告
• 遵循 Coding Standards

测试

• 新功能有对应的单元测试
• 所有测试通过 (./scripts/core/test)
• Bug 修复包含回归测试

文档

• API 变更已更新文档
• 必要时更新 CHANGELOG.md
• 公共接口有 Doxygen 注释

---

PR 注意事项

• 提交信息要简洁明了
• 每个提交只做一件事
• 避免过于宽泛的描述
• 使用英文撰写提交信息
• 大的变更请先创建 Issue 讨论

---

添加新功能检查清单

添加新的过滤谓词

1. 在 include/fqtools/processing/ 添加新 Predicate 类声明
2. 在 src/processing/predicates/ 添加实现
3. 在 src/cli/commands/ 中注册 CLI 选项
4. 添加单元测试到 tests/unit/
5. 更新 CLI 参考文档

添加新的子命令

1. 在 src/cli/commands/ 创建新的 Command 类
2. 在 main.cpp 中注册命令
3. 添加集成测试和 E2E 测试
4. 更新 CLI 参考文档

---

发布流程

# 1. 更新版本号
# CMakeLists.txt 和 conanfile.py 中的 version

# 2. 更新 CHANGELOG.md

# 3. 创建 tag
git tag -a v3.2.0 -m "Release v3.2.0"
git push origin v3.2.0

# 4. GitHub Actions 自动触发 release workflow

---

联系方式

• Issues: GitHub Issues
• Pull Requests: GitHub PRs

---

相关页面

• Getting Started — 环境搭建
• Coding Standards — 编码规范详解
• Testing Strategy — 测试策略
• Build and CI — 构建与 CI 流程