# Contributing to Intent Engine
感谢你对 Intent Engine 项目的关注！我们欢迎各种形式的贡献。
## 开发环境设置
### 前置要求
- Rust 1.70+ (推荐使用 rustup)
- Git
### 克隆仓库
```bash
git clone https://github.com/wayfind/intent-engine.git
cd intent-engine
```
### 构建项目
```bash
cargo build
```
### 运行测试
```bash
cargo test
```
### 运行 doctor 命令
```bash
cargo run -- doctor
```
## 提交代码前的检查清单
在提交 Pull Request 之前，请确保通过以下所有检查：
### 1. 代码格式化
```bash
cargo fmt --all
```
### 2. Clippy 检查
```bash
cargo clippy --all-targets --all-features -- -D warnings
```
### 3. 运行所有测试
```bash
cargo test --all-features
```
### 4. 文档测试
```bash
cargo test --doc --all-features
```
### 5. 构建文档
```bash
cargo doc --no-deps --all-features
```
### 6. 运行基准测试（可选）
```bash
cargo bench
```
## CI/CD 流程
我们的 CI 系统会自动运行多个检查：
### 主要 CI 任务
1. **多平台测试** - 在 Linux、macOS 和 Windows 上测试
2. **多版本测试** - 测试 stable、beta 和 nightly Rust
3. **代码格式检查** - 确保代码风格一致
4. **Clippy 检查** - 捕获常见错误和代码质量问题
5. **代码覆盖率** - 使用 cargo-tarpaulin 生成覆盖率报告
6. **安全审计** - 使用 cargo-audit 和 cargo-deny 检查依赖
7. **文档构建** - 验证文档可以正确生成
8. **包验证** - 确保可以发布到 crates.io
9. **最小依赖版本测试** - 确保与最小版本兼容
10. **安装脚本测试** - 验证安装流程
### CI 触发条件
- 推送到 `main`、`master` 或 `claude/**` 分支
- 创建 Pull Request 到 `main` 或 `master`
- 每天 UTC 00:00 自动运行（检查依赖问题）
### 本地运行完整 CI 检查
```bash
# 格式化
cargo fmt --all
# Clippy
cargo clippy --all-targets --all-features -- -D warnings
# 测试
cargo test --all-features
# 文档
cargo doc --no-deps --all-features
# 安装 cargo-audit（首次）
cargo install cargo-audit
# 运行安全审计
cargo audit
# 安装 cargo-deny（首次）
cargo install cargo-deny
# 运行 cargo-deny 检查
cargo deny check
# 包检查
cargo package --allow-dirty
# Doctor 命令
cargo run --release -- doctor
```
## Pull Request 流程
1. **Fork 仓库**到你的 GitHub 账户
2. **创建功能分支** (`git checkout -b feature/amazing-feature`)
3. **提交你的更改** (`git commit -m 'Add some amazing feature'`)
4. **推送到分支** (`git push origin feature/amazing-feature`)
5. **创建 Pull Request**
### Pull Request 最佳实践
- **清晰的标题和描述** - 解释你的更改和原因
- **小型、聚焦的 PR** - 每个 PR 应该专注于一个功能或修复
- **测试覆盖** - 为新功能添加测试
- **更新文档** - 如果 API 发生变化，更新文档
- **遵循代码风格** - 运行 `cargo fmt`
- **通过所有 CI 检查** - 确保所有自动化测试通过
## 提交信息规范
我们使用 Conventional Commits 格式：
```
<type>(<scope>): <subject>
<body>
<footer>
```
**类型 (type):**
- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `style`: 代码格式（不影响代码运行）
- `refactor`: 代码重构
- `perf`: 性能优化
- `test`: 添加测试
- `chore`: 构建过程或辅助工具的变动
- `ci`: CI 配置文件和脚本的变动
- `deps`: 依赖更新
**示例:**
```
feat(tasks): add priority and complexity fields
Add support for task priority (1-10) and complexity (1-10) to help
with task scheduling and workload estimation.
Closes #123
```
## 代码审查
所有提交都需要通过代码审查。审查者会检查：
- 代码质量和可读性
- 测试覆盖率
- 性能影响
- 安全考虑
- 向后兼容性
- 文档完整性
## 报告 Bug
使用 GitHub Issues 报告 bug，请包含：
1. **清晰的标题**
2. **重现步骤**
3. **预期行为**
4. **实际行为**
5. **环境信息** (OS, Rust 版本等)
6. **相关日志或错误信息**
## 功能请求
我们欢迎功能建议！请创建一个 GitHub Issue，包含：
1. **用例描述** - 为什么需要这个功能
2. **建议的解决方案** - 你希望如何实现
3. **替代方案** - 其他可能的实现方式
4. **附加上下文** - 任何其他相关信息
## 安全问题
如果发现安全漏洞，请**不要**创建公开的 Issue。请发送邮件到项目维护者。
## 许可证
通过提交代码，你同意你的贡献将使用 MIT OR Apache-2.0 双重许可证。
## 行为准则
- **尊重他人** - 保持友好和专业
- **建设性反馈** - 提供有帮助的建议
- **包容性** - 欢迎所有背景的贡献者
- **耐心** - 记住每个人都在学习
## 获取帮助
- 📖 阅读 [文档](./README.md)
- 💬 在 GitHub Discussions 提问
- 🐛 报告 [Issues](https://github.com/wayfind/intent-engine/issues)
---
再次感谢你的贡献！ 🎉