贡献指南

感谢您对 dbnexus 项目的关注！本文档描述了参与开发所需的流程和规范。

开发环境

Rust 1.91+（edition 2024）
Git（配置了 pre-commit hooks）
Docker（可选，用于 PostgreSQL/MySQL 集成测试）

初始化

git clone https://github.com/Kirky-X/dbnexus.git
cd dbnexus

# 安装 pre-commit hooks
./scripts/install-pre-commit.sh

# 验证环境
cargo build --all-features
cargo test --all-features --lib

TDD 工作流

本项目采用测试驱动开发（TDD），每个开发任务组必须遵循以下循环：

定接口：先定义 trait / API 签名（trait Xxx { ... }），不写实现
写测试：基于接口编写单元测试（#[cfg(test)] mod tests { ... }），此时测试应失败（red）
写代码：实现接口，使测试通过（green）
跑测试：cargo test --features <对应特性> --lib，确保所有测试通过
commit：通过后执行 git add . && git commit -m "feat(<模块>): <描述>"
gitnexus analyze：用 gitnexus 工具分析本任务对其他模块的影响，识别需联动修改的代码
继续下一个：基于 analyze 结果调整后续任务，再开始下一轮循环

Pre-commit Hooks

项目使用 pre-commit hooks 保证代码质量：

# 安装
./scripts/install-pre-commit.sh

# 手动运行
pre-commit run --all-files

禁止事项

禁止使用 --no-verify 跳过 pre-commit hooks
禁止使用 git commit -n 绕过检查
违反此规定视为质量红线事件

代码质量

项目集成多个质量工具，贡献前请确保通过以下检查：

diting — 代码质量审查

用于代码简化、架构优化、性能审查。触发场景：

review / audit / tech debt / over-engineering / simplify
任意 write / add / refactor / fix 任务

tiangang — SAST 安全扫描

用于安全审查、漏洞扫描。触发场景：

安全审查 / 漏洞扫描 / SAST
hardcoded secrets / SQL injection / unsafe eval
发布前安全检查

kueiku — 方法论框架

用于硬性 bug 分析、根因分析、结构化思考。触发场景：

分析 / 策略 / 决策 / 根因分析

Pull Request 流程

创建 feature 分支

git checkout -b feat/<your-feature>
# 或
git checkout -b fix/<bug-description>

确保 pre-commit hooks 通过
```
pre-commit run --all-files
```

确保测试通过

cargo test --all-features
cargo clippy --all-features -- -D warnings
cargo fmt --all -- --check

提交 PR
- 标题格式：feat(<模块>): <描述> 或 fix(<模块>): <描述>
- 描述变更内容和原因
- 关联相关 issue

代码风格

通用规范

遵循现有代码库命名和架构惯例（即使你认为自己的写法更好）
依赖必须通过 feature 门控，不引入未门控的依赖
edition 2024，rust 1.91+
MIT License

Rust 规范

命名：snake_case（函数/变量/模块），CamelCase（类型/Trait）
错误处理：使用 Result<T, E> 返回错误，严禁吞掉错误（规则 12）
禁止 unsafe 代码（#![forbid(unsafe_code)]）
必须有文档注释（#![deny(missing_docs)]）

Feature 门控规范

# Cargo.toml 中正确门控示例
[features]
my-feature = ["dep:some-crate"]

[dependencies]
some-crate = { version = "1.0", optional = true }

// src/lib.rs 中正确门控示例
#[cfg(feature = "my-feature")]
pub mod my_module;

测试规范

测试要验证正确行为的有意义属性（值、结构、副作用、错误类型）
不仅验证"函数有返回值"或"不报错"
"所有测试通过"是必要条件但非充分条件
测试太弱时要明确指出

运行测试

# 单元测试
cargo test --features sqlite --lib

# 集成测试
cargo test --features sqlite

# 全部测试
cargo test --all-features

# 特定数据库后端
cargo test --features postgres
cargo test --features mysql

许可证

提交的代码将采用 MIT 许可证，与项目保持一致。

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History