贡献到 BotRS

感谢您对贡献 BotRS 的兴趣！本指南将帮助您开始为项目做出贡献。

行为准则

通过参与此项目，您同意遵守我们的行为准则。请在贡献之前阅读。

开始使用

前置条件

• Rust 1.70 或更高版本
• Git
• 一个 QQ 频道机器人应用程序（用于测试）

设置开发环境

1. 在 GitHub 上 Fork 仓库

2. 在本地克隆您的 Fork：

   git clone https://github.com/YOUR_USERNAME/botrs.git
   cd botrs

3. 添加上游仓库：

   git remote add upstream https://github.com/YinMo19/botrs.git

4. 安装依赖项：

   cargo build

5. 运行测试以确保一切正常：

   cargo test

开发工作流程

在进行更改之前

1. 为您的功能或修复创建新分支：

   git checkout -b feature/你的功能名称

2. 保持您的分支与上游同步：

   git fetch upstream
   git rebase upstream/main

进行更改

1. 遵循我们的编码标准编写代码
2. 为新功能添加测试
3. 如果需要，更新文档
4. 确保所有测试通过：

   cargo test
   cargo clippy
   cargo fmt

提交更改

1. 使用清晰、描述性的消息提交更改：

   git commit -m "feat: 添加对新消息类型的支持"

2. 推送到您的 Fork：

   git push origin feature/你的功能名称

3. 在 GitHub 上创建 Pull Request

贡献类型

错误报告

在报告错误时，请包括：

• 问题的清晰描述
• 重现问题的步骤
• 预期与实际行为
• 您的环境（Rust 版本、操作系统等）
• 相关的代码示例或日志

使用我们的错误报告模板。

功能请求

对于功能请求，请包括：

• 功能的清晰描述
• 用例和动机
• 来自其他库的任何相关示例
• 愿意自己实现功能

使用我们的功能请求模板。

代码贡献

我们欢迎以下贡献：

• 错误修复
• 新功能
• 性能改进
• 文档更新
• 示例代码
• 测试覆盖率改进

编码标准

Rust 指南

• 遵循 Rust API 指南
• 使用 cargo fmt 进行代码格式化
• 解决所有 cargo clippy 警告
• 为公共 API 编写全面的文档
• 为所有新功能添加测试

代码风格

// 使用描述性名称
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 处理错误类型
• 在错误链中包含上下文

测试

• 为所有公共函数编写单元测试
• 对复杂工作流程使用集成测试
• 尽可能模拟外部依赖项
• 争取高测试覆盖率

#[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

测试

运行测试

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_name

# 运行带输出的测试
cargo test -- --nocapture

# 运行集成测试
cargo test --test integration_tests

测试环境

设置测试环境变量：

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 提交风格是：

[type] simple message

- detail message 1: detailed description.
- detail message 2: detailed description.
- detail message 3: detailed description.
- detail message 4: detailed description.
- etc.

例如：

[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. 您的贡献将在发布中得到认可

发布流程

版本控制

我们遵循语义化版本控制：

• MAJOR: 不兼容的 API 更改
• MINOR: 向后兼容的功能
• PATCH: 向后兼容的错误修复

发布清单

1. 更新 Cargo.toml 中的版本
2. 更新 CHANGELOG.md
3. 创建发布标签
4. 发布到 crates.io
5. 更新文档

社区

获取帮助

• GitHub 讨论 用于问题
• Discord 服务器 用于实时聊天
• GitHub Issues 用于错误和功能

认可

贡献者在以下方面得到认可：

• 发布说明
• README 中的贡献者部分
• 文档中的名人堂

许可证

通过为 BotRS 做出贡献，您同意您的贡献将在 MIT 许可证下获得许可。

有问题吗？

如果您对贡献有疑问，请：

1. 检查现有的问题和讨论
2. 在我们的 Discord 服务器中询问
3. 在 GitHub 上开启讨论
4. 直接联系维护者

感谢您为 BotRS 做出贡献！🚀