# 贡献到 BotRS
感谢您对贡献 BotRS 的兴趣！本指南将帮助您开始为项目做出贡献。
## 行为准则
通过参与此项目，您同意遵守我们的[行为准则](./CODE_OF_CONDUCT.md)。请在贡献之前阅读。
## 开始使用
### 前置条件
- Rust 1.70 或更高版本
- Git
- 一个 QQ 频道机器人应用程序（用于测试）
### 设置开发环境
1. 在 GitHub 上 Fork 仓库
2. 在本地克隆您的 Fork：
```bash
git clone https://github.com/YOUR_USERNAME/botrs.git
cd botrs
```
3. 添加上游仓库：
```bash
git remote add upstream https://github.com/YinMo19/botrs.git
```
4. 安装依赖项：
```bash
cargo build
```
5. 运行测试以确保一切正常：
```bash
cargo test
```
## 开发工作流程
### 在进行更改之前
1. 为您的功能或修复创建新分支：
```bash
git checkout -b feature/你的功能名称
```
2. 保持您的分支与上游同步：
```bash
git fetch upstream
git rebase upstream/main
```
### 进行更改
1. 遵循我们的[编码标准](#编码标准)编写代码
2. 为新功能添加测试
3. 如果需要，更新文档
4. 确保所有测试通过：
```bash
cargo test
cargo clippy
cargo fmt
```
### 提交更改
1. 使用清晰、描述性的消息提交更改：
```bash
git commit -m "feat: 添加对新消息类型的支持"
```
2. 推送到您的 Fork：
```bash
git push origin feature/你的功能名称
```
3. 在 GitHub 上创建 Pull Request
## 贡献类型
### 错误报告
在报告错误时，请包括：
- 问题的清晰描述
- 重现问题的步骤
- 预期与实际行为
- 您的环境（Rust 版本、操作系统等）
- 相关的代码示例或日志
使用我们的[错误报告模板](./bug_report.md)。
### 功能请求
对于功能请求，请包括：
- 功能的清晰描述
- 用例和动机
- 来自其他库的任何相关示例
- 愿意自己实现功能
使用我们的[功能请求模板](./feature_request.md)。
### 代码贡献
我们欢迎以下贡献：
- 错误修复
- 新功能
- 性能改进
- 文档更新
- 示例代码
- 测试覆盖率改进
## 编码标准
### Rust 指南
- 遵循 [Rust API 指南](https://rust-lang.github.io/api-guidelines/)
- 使用 `cargo fmt` 进行代码格式化
- 解决所有 `cargo clippy` 警告
- 为公共 API 编写全面的文档
- 为所有新功能添加测试
### 代码风格
```rust
// 使用描述性名称
pub struct MessageParams {
content: Option<String>,
embed: Option<MessageEmbed>,
}
// 记录公共 API
/// 创建具有文本内容的新消息。
///
/// # 参数
///
/// * `content` - 消息的文本内容
///
/// # 示例
///
/// ```
/// let params = MessageParams::new_text("你好，世界！");
/// ```
pub fn new_text(content: impl Into<String>) -> Self {
Self {
content: Some(content.into()),
embed: None,
}
}
```
### 错误处理
- 对可能失败的操作使用 `Result<T, BotError>`
- 提供有意义的错误消息
- 使用 `thiserror` 处理错误类型
- 在错误链中包含上下文
### 测试
- 为所有公共函数编写单元测试
- 对复杂工作流程使用集成测试
- 尽可能模拟外部依赖项
- 争取高测试覆盖率
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_message_params_creation() {
let params = MessageParams::new_text("test");
assert_eq!(params.content, Some("test".to_string()));
}
#[tokio::test]
async fn test_api_call() {
// 测试异步功能
}
}
```
## 文档
### 代码文档
- 使用 `///` 注释记录所有公共 API
- 在文档中包含示例
- 解释复杂的算法和设计决策
- 使用 `cargo doc` 生成和审查文档
### 用户文档
- 添加功能时更新相关指南
- 在文档站点中包含示例
- 保持更新日志最新
- 如果需要，更新 README.md
## 测试
### 运行测试
```bash
# 运行所有测试
cargo test
# 运行特定测试
cargo test test_name
# 运行带输出的测试
cargo test -- --nocapture
# 运行集成测试
cargo test --test integration_tests
```
### 测试环境
设置测试环境变量：
```bash
export QQ_BOT_APP_ID="test_app_id"
export QQ_BOT_SECRET="test_secret"
export RUST_LOG="debug"
```
### 编写测试
- 测试成功和失败情况
- 使用描述性测试名称
- 保持测试专注和独立
- 尽可能模拟外部 API
## Pull Request 流程
### 提交之前
1. 确保所有测试通过
2. 运行 `cargo clippy` 并解决警告
3. 运行 `cargo fmt` 格式化代码
4. 如果需要，更新文档
5. 为重要更改添加更新日志条目
### PR 要求
- 清晰的标题和描述
- 引用相关问题
- 包含新功能的测试
- 更新文档
- 遵循我们的提交消息格式
### 提交消息格式
欢迎贡献代码！我的个人 git commit 提交风格是：
```text
[type] simple message
- detail message 1: detailed description.
- detail message 2: detailed description.
- detail message 3: detailed description.
- detail message 4: detailed description.
- etc.
```
例如：
```text
[feature] add structured message parameters API
- models/message.rs: add MessageParams, GroupMessageParams, C2CMessageParams, DirectMessageParams structs.
- api.rs: add post_*_with_params methods for structured parameter sending.
- examples/: add demo_new_message_api.rs showing the new API usage.
- deprecate old multi-parameter API methods but keep backward compatibility.
```
### 审查流程
1. 维护者将审查您的 PR
2. 解决反馈和请求的更改
3. 一旦获得批准，您的 PR 将被合并
4. 您的贡献将在发布中得到认可
## 发布流程
### 版本控制
我们遵循[语义化版本控制](https://semver.org/)：
- `MAJOR`: 不兼容的 API 更改
- `MINOR`: 向后兼容的功能
- `PATCH`: 向后兼容的错误修复
### 发布清单
1. 更新 `Cargo.toml` 中的版本
2. 更新 `CHANGELOG.md`
3. 创建发布标签
4. 发布到 crates.io
5. 更新文档
## 社区
### 获取帮助
- [GitHub 讨论](https://github.com/YinMo19/botrs/discussions) 用于问题
- [Discord 服务器](https://discord.gg/eRRkYfcG8u) 用于实时聊天
- [GitHub Issues](https://github.com/YinMo19/botrs/issues) 用于错误和功能
### 认可
贡献者在以下方面得到认可：
- 发布说明
- README 中的贡献者部分
- 文档中的名人堂
## 许可证
通过为 BotRS 做出贡献，您同意您的贡献将在 MIT 许可证下获得许可。
## 有问题吗？
如果您对贡献有疑问，请：
1. 检查现有的问题和讨论
2. 在我们的 Discord 服务器中询问
3. 在 GitHub 上开启讨论
4. 直接联系维护者
感谢您为 BotRS 做出贡献！🚀