DCTS/docs/contributing.md

DCTS 开发者与参与贡献指南 (Contributing Guide)

感谢关注并参与 DCTS (Distributed Computing TLUSTY/SYNSPEC) 的开发！本文档为开发者提供本地环境配置、代码库结构说明及测试规范。

---

1. 本地开发环境准备

必备依赖

• Rust 工具链：1.75+ (推荐使用 rustup 安装)
• C/Fortran 编译器（计算节点模拟调试需 gfortran 或预编译好的二进制）
• SQLite 3开发库（嵌入在 Rust dependencies 中，无需额外安装系统库）

克隆与编译

cd dcts
cargo check --workspace --all-targets
cargo build

---

2. 代码库结构 (Workspace Layout)

dcts/
├── Cargo.toml               # Workspace 根配置
├── config.yaml              # 示例网格配置文件
├── crates/
│   ├── common/              # [Library] 物理计算引擎、子进程管理、收敛检测与模板
│   ├── server/              # [Binary] Axum HTTP REST 服务端与 Scheduler
│   ├── node/                # [Binary] Worker 节点 Daemon 与任务抢占回路
│   └── mq/                  # [Library] SQLite 事务型分布式任务队列
├── tools/
│   └── sync_seeds/          # [Binary] 离线/增量种子同步 CLI 工具
└── docs/                    # 分主题架构与规格技术文档

---

3. 测试与规范 (Testing & Guidelines)

3.1 运行单元测试与集成测试

# 运行 Workspace 内所有单元测试
cargo test --workspace

# 针对核心物理解析模块独立测试
cargo test -p common

3.2 代码风格与 Linting

提交 PR 前请确保以下命令无 error 和 warning：

# 代码格式化
cargo fmt --all -- --check

# Rust 官方 Linter 静态检查
cargo clippy --workspace --all-targets -- -D warnings

---

4. 提交 Code Review 规范

1. 分支策略：从 main 切出特性分支，推荐命名如 feature/seed-optimizer 或 fix/stale-node-leak。
2. Commit Message 规范：格式推荐使用 module: succinct explanation，如：
   • common: add tolerance factor check for seed finder
   • server: fix sqlite connection pool leak under heavy load
3. 保持文档更新：若修改了 API 接口定义或数据库 Schema，请同步更新 docs/api_reference.md 与 docs/database.md。