# Contributing to BotRS

Thank you for your interest in contributing to BotRS! This guide will help you get started with contributing to the project.

## Code of Conduct

By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please read it before contributing.

## Getting Started

### Prerequisites

- Rust 1.70 or later
- Git
- A QQ Guild Bot application (for testing)

### Setting Up Your Development Environment

1. Fork the repository on GitHub
2. Clone your fork locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/botrs.git
   cd botrs
   ```

3. Add the upstream repository:
   ```bash
   git remote add upstream https://github.com/YinMo19/botrs.git
   ```

4. Install dependencies:
   ```bash
   cargo build
   ```

5. Run tests to ensure everything works:
   ```bash
   cargo test
   ```

## Development Workflow

### Before Making Changes

1. Create a new branch for your feature or fix:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Keep your branch up to date with upstream:
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```

### Making Changes

1. Write your code following our [coding standards](#coding-standards)
2. Add tests for new functionality
3. Update documentation if needed
4. Ensure all tests pass:
   ```bash
   cargo test
   cargo clippy
   cargo fmt
   ```

### Submitting Changes

1. Commit your changes with clear, descriptive messages:
   ```bash
   git commit -m "feat: add support for new message type"
   ```

2. Push to your fork:
   ```bash
   git push origin feature/your-feature-name
   ```

3. Create a Pull Request on GitHub

## Types of Contributions

### Bug Reports

When reporting bugs, please include:

- A clear description of the issue
- Steps to reproduce the problem
- Expected vs actual behavior
- Your environment (Rust version, OS, etc.)
- Relevant code samples or logs

Use our [bug report template](bug_report.md).

### Feature Requests

For feature requests, please include:

- A clear description of the feature
- The use case and motivation
- Any relevant examples from other libraries
- Willingness to implement the feature yourself

Use our [feature request template](feature_request.md).

### Code Contributions

We welcome contributions for:

- Bug fixes
- New features
- Performance improvements
- Documentation updates
- Example code
- Test coverage improvements

## Coding Standards

### Rust Guidelines

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `cargo fmt` for code formatting
- Address all `cargo clippy` warnings
- Write comprehensive documentation for public APIs
- Add tests for all new functionality

### Code Style

```rust
// Use descriptive names
pub struct MessageParams {
    content: Option<String>,
    embed: Option<MessageEmbed>,
}

// Document public APIs
/// Creates a new message with text content.
///
/// # Arguments
///
/// * `content` - The text content of the message
///
/// # Example
///
/// ```
/// let params = MessageParams::new_text("Hello, world!");
/// ```
pub fn new_text(content: impl Into<String>) -> Self {
    Self {
        content: Some(content.into()),
        embed: None,
    }
}
```

### Error Handling

- Use `Result<T, BotError>` for fallible operations
- Provide meaningful error messages
- Use `thiserror` for error types
- Include context in error chains

### Testing

- Write unit tests for all public functions
- Use integration tests for complex workflows
- Mock external dependencies when possible
- Aim for high test coverage

```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() {
        // Test async functionality
    }
}
```

## Documentation

### Code Documentation

- Document all public APIs with `///` comments
- Include examples in documentation
- Explain complex algorithms and design decisions
- Use `cargo doc` to generate and review documentation

### User Documentation

- Update relevant guides when adding features
- Include examples in the documentation site
- Keep the changelog updated
- Update README.md if needed

## Testing

### Running Tests

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run integration tests
cargo test --test integration_tests
```

### Test Environment

Set up test environment variables:

```bash
export QQ_BOT_APP_ID="test_app_id"
export QQ_BOT_SECRET="test_secret"
export RUST_LOG="debug"
```

### Writing Tests

- Test both success and failure cases
- Use descriptive test names
- Keep tests focused and independent
- Mock external APIs when possible

## Pull Request Process

### Before Submitting

1. Ensure all tests pass
2. Run `cargo clippy` and address warnings
3. Run `cargo fmt` to format code
4. Update documentation if needed
5. Add changelog entry for significant changes

### PR Requirements

- Clear title and description
- Reference related issues
- Include tests for new functionality
- Update documentation
- Follow our commit message format

### Commit Message Format

We use conventional commits:

```
[type(scope)]: description

- body: detailed description of changes
- body: detailed description of changes
- body: detailed description of changes
```

Types:
- `feat`: new feature
- `fix`: bug fix
- `docs`: documentation changes
- `style`: formatting changes
- `refactor`: code refactoring
- `test`: adding tests
- `chore`: maintenance tasks

Examples:
```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.
```

### Review Process

1. Maintainers will review your PR
2. Address feedback and requested changes
3. Once approved, your PR will be merged
4. Your contribution will be credited in releases

## Release Process

### Versioning

We follow [Semantic Versioning](https://semver.org/):

- `MAJOR`: incompatible API changes
- `MINOR`: backwards-compatible functionality
- `PATCH`: backwards-compatible bug fixes

### Release Checklist

1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Create release tag
4. Publish to crates.io
5. Update documentation

## Community

### Getting Help

- [GitHub Discussions](https://github.com/YinMo19/botrs/discussions) for questions
- [Discord Server](https://discord.gg/eRRkYfcG8u) for real-time chat
- [GitHub Issues](https://github.com/YinMo19/botrs/issues) for bugs and features

### Recognition

Contributors are recognized in:

- Release notes
- Contributors section in README
- Hall of Fame in documentation

## License

By contributing to BotRS, you agree that your contributions will be licensed under the MIT License.

## Questions?

If you have questions about contributing, please:

1. Check existing issues and discussions
2. Ask in our Discord server
3. Open a discussion on GitHub
4. Contact maintainers directly

Thank you for contributing to BotRS! 🚀
