> 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 ## Contributing to Vector SDK Thank you for considering contributing to Vector SDK! This document provides guidelines for contributing to the project. *** ## Table of Contents * [Code of Conduct](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#code-of-conduct) * [Getting Started](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#getting-started) * [Development Setup](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#development-setup) * [Coding Standards](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#coding-standards) * [Testing](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#testing) * [Pull Requests](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#pull-requests) * [Documentation](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#documentation-1) * [Releases](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#releases) * [Security](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#security) * [Questions (Support)](https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/files/editor-1#questions) *** ### Code of Conduct Please note that this project is released with a [Contributor Code of Conduct](https://github.com/VectorPrivacy/Vector-SDK/blob/mls-groups/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. *** ### Getting Started 1. **Fork the repository** on GitHub 2. **Clone your fork** locally: ``` git clone https://github.com/your-username/Vector-SDK.git cd Vector-SDK ``` 3. **Add the upstream remote** to keep your fork in sync: ``` git remote add upstream https://github.com/VectorPrivacy/Vector-SDK.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 ``` # Clone the repository git clone https://github.com/VectorPrivacy/Vector-SDK.git cd Vector-SDK # Build the project cargo build # Build with release optimization cargo build --release ``` #### Running Tests ``` # Run all tests cargo test # Run tests with verbose output cargo test -- --nocapture # Run specific test cargo test 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 * Follow the format: ``` /// 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 * Use the `thiserror` crate for defining error types * Provide clear, actionable error messages * Implement proper error conversion with `From` trait #### Logging * Use the `log` crate for logging * Follow these log levels: * `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 * Integration tests: In the `tests/` directory * Example tests: In the separate examples repository #### Writing Tests ``` #[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 } } ``` #### Test Coverage * Aim for high test coverage (80%+) * Test edge cases and error conditions * Test async code properly with `tokio::test` *** ### Pull Requests #### Creating a Pull Request 1. **Create a feature branch** from `main`: ``` git checkout -b feature/your-feature-name ``` 2. **Make your changes** following the coding standards 3. **Commit your changes** with clear, descriptive messages: ``` git commit -m "feat: add new feature description" git commit -m "fix: resolve issue with description" ``` 4. **Push to your fork**: ``` git push origin feature/your-feature-name ``` 5. **Open a Pull Request** on GitHub with: * Clear title describing the change * Detailed description of what was changed and why * Related issues (if any) * Screenshots or examples (if applicable) #### Pull Request Requirements * All tests must pass * Code must be properly formatted (run `cargo fmt`) * Code must pass linting (run `cargo clippy`) * Documentation must be updated * Changes must follow the coding standards *** ### Documentation #### Updating Documentation * Update the README.md for major changes * Update CHANGELOG.md for new features and fixes * Add or update Rustdoc comments for code changes * Update any relevant documentation files #### Generating Documentation To generate and view the API documentation: ``` # Generate documentation cargo doc --open # Generate documentation with nightly features cargo +nightly doc --open --no-deps ``` *** ### Releases #### Versioning This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html): * `MAJOR` version when making breaking changes * `MINOR` version when adding functionality in a backwards-compatible manner * `PATCH` version when making backwards-compatible bug fixes #### Release Process 1. Update CHANGELOG.md with release notes 2. Update version in Cargo.toml 3. Create a git tag: ``` git tag -a vX.Y.Z -m "Release vX.Y.Z" git push origin vX.Y.Z ``` 4. Publish to crates.io: ``` cargo publish ``` *** ### Security #### Reporting Security Issues If you discover a security vulnerability, please: 1. Do not open a public issue 2. Email the maintainers directly at 3. Include as much detail as possible #### Security Best Practices * Always use secure random number generation * Validate all inputs * Use proper encryption for sensitive data * Follow the principle of least privilege * Keep dependencies updated *** ### Questions If you have any questions about contributing, please open an issue on GitHub or contact the maintainers. Additional help can be found in the [Vector Community Discord](https://discord.gg/ar2pnE9Huy). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://vector-privacy.gitbook.io/vector-privacy/vector-sdk/docs/contributing.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.