> For the complete documentation index, see [llms.txt](https://vector-privacy.gitbook.io/vector-privacy/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/contributing.md).

# Contributing

How to Contribute to Vector SDK

Thank you for considering contributing to Vector SDK! This document provides guidelines for contributing to the project.

{% hint style="info" %}
Vector SDK lives inside the main [Vector](https://github.com/VectorPrivacy/Vector) repository, under `crates/vector-sdk`, rather than as a standalone repo. All commands below assume you're working from that path. 
{% endhint %}

## Table of Contents

* [Code of Conduct](#code-of-conduct)
* [Getting Started](#getting-started)
* [Development Setup](#development-setup)
* [Coding Standards](#coding-standards)
* [Testing](#testing)
* [Pull Requests](#pull-requests)
* [Documentation](#documentation-1)
* [Releases](#releases)
* [Security](#security)
* [Questions (Support)](#questions-support)

***

### Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

***

### Getting Started

1. Fork the [Vector](https://github.com/VectorPrivacy/Vector) repository on GitHub.
2. Clone your fork locally:

```bash
git clone https://github.com/your-username/Vector.git
cd Vector
```

3. Add the upstream remote to keep your fork in sync:

```bash
git remote add upstream https://github.com/VectorPrivacy/Vector.git
```

***

### Development Setup

#### Prerequisites

* Rust (latest stable version)
* Cargo (Rust package manager)
* Git
* Optional: Rustfmt and Clippy for code formatting and linting

#### Building the Project

```bash
# From the repository root
cd crates/vector-sdk

# Build the crate
cargo build -p vector-sdk

# Build with release optimization
cargo build -p vector-sdk --release
```

#### Running Tests

```bash
# Run all tests for the SDK
cargo test -p vector-sdk

# Run tests with verbose output
cargo test -p vector-sdk -- --nocapture

# Run a specific test
cargo test -p vector-sdk test_name
```

***

### Coding Standards

#### Rust Style Guide

* Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
* Use `snake_case` for variables and functions
* Use `PascalCase` for types and enums
* Use `UPPER_CASE` for constants
* Keep lines under 100 characters when possible
* Use 4 spaces for indentation (Rust's default)

#### Documentation

Document all public items with Rustdoc comments, following this format:

```rust
/// Summary line ending with a period.
///
/// Additional details if needed.
///
/// # Arguments
///
/// * `param` - Description of parameter.
///
/// # Returns
///
/// Description of return value.
pub fn example_function(param: Type) -> ReturnType {
    // Implementation
}
```

#### Error Handling

* Bot-facing errors flow through `vector_sdk::Error` / `vector_sdk::Result`, re-exported directly from `vector-core`
* Provide clear, actionable error messages
* Implement proper error conversion with the `From` trait where it makes the calling code cleaner

#### Logging

Use the `log` crate for logging, following these log levels:

| Level   | Use for                                 |
| ------- | --------------------------------------- |
| `error` | Critical errors that need attention     |
| `warn`  | Potential issues or deprecated features |
| `info`  | Important operational messages          |
| `debug` | Detailed debugging information          |
| `trace` | Very detailed tracing information       |

***

### Testing

#### Test Organization

* **Unit tests:** In the same file as the implementation, in a `#[cfg(test)]` module. The SDK's own `invite_policy_matrix` and `channel_kind_auto_detection` tests in `lib.rs` are good reference examples.
* **Integration tests:** In the `tests/` directory.
* **Example bots:** In `examples/`, runnable end-to-end as living documentation rather than as automated tests.

#### Writing Tests

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_function_name() {
        // Test implementation
        assert_eq!(expected, actual);
    }

    #[test]
    #[should_panic(expected = "error message")]
    fn test_panics() {
        // Code that should panic
    }
}
```

{% hint style="success" %}
Aim for high test coverage on new logic, and make sure to test edge cases, error conditions, and async code (with `#[tokio::test]`) rather than only the happy path.
{% endhint %}

***

### Pull Requests

#### Creating a Pull Request

1. Create a feature branch from `master`:

```bash
git checkout -b feature/your-feature-name
```

2. Make your changes following the coding standards above.
3. Commit your changes with clear, descriptive messages:

```bash
git commit -m "feat(sdk): add new feature description"
git commit -m "fix(sdk): resolve issue with description"
```

4. Push to your fork:

```bash
git push origin feature/your-feature-name
```

5. Open a Pull Request on GitHub with:
   * A clear title describing the change
   * A detailed description of what was changed and why
   * Related issues, if any
   * Screenshots or examples, if applicable

#### Pull Request Requirements

{% hint style="warning" %}
**All of the following must be true before a pull request will be merged:**

* All tests pass
* Code is properly formatted (`cargo fmt`)
* Code passes linting (`cargo clippy`)
* Documentation is updated
* Changes follow the coding standards above
  {% endhint %}

***

### Documentation

#### Updating Documentation

* Update `README.md` for major changes
* Update `CHANGELOG.md` for new features and fixes
* Add or update Rustdoc comments for code changes
* Update any relevant GitBook pages, including this one, when developer-facing behavior changes

#### Generating Documentation

To generate and view the API documentation locally:

```bash
# Generate documentation
cargo doc -p vector-sdk --open

# Generate documentation with nightly features
cargo +nightly doc -p vector-sdk --open --no-deps
```

***

### Releases

#### Versioning

This project follows [Semantic Versioning](https://semver.org/):

* **MAJOR** version when making breaking changes
* **MINOR** version when adding functionality in a backwards-compatible manner
* **PATCH** version when making backwards-compatible bug fixes

{% hint style="info" %}
The SDK's crate version is independent of the main Vector app's release version. See the [version compatibility note](/vector-privacy/vector-sdk/readme.md) on the main SDK page for details. 
{% endhint %}

#### Release Process

1. Update `CHANGELOG.md` with release notes.
2. Update the version in `crates/vector-sdk/Cargo.toml`.
3. Create a git tag:

```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z
```

4. Publish to crates.io:

```bash
cargo publish -p vector-sdk
```

***

### Security

#### Reporting Security Issues

{% hint style="danger" %}
If you discover a security vulnerability, please **do not open a public issue**.
{% endhint %}

Instead:

* Email the maintainers directly at `security@vectorapp.io`
* Include as much detail as possible

See the [Security](/vector-privacy/vector-sdk/docs/security.md) page for the full policy and best practices.

***

### Questions (Support)

If you have any questions about contributing, please open an issue on [GitHub](https://github.com/vectorprivacy/vector), contact the maintainers, or ask in the [Vector Community](https://chat.vectorapp.io/) on Vector or [Discord](https://discord.gg/u2YrX7RUCJ).