Skip to content

Latest commit

 

History

History
159 lines (110 loc) · 3.95 KB

CONTRIBUTING.md

File metadata and controls

159 lines (110 loc) · 3.95 KB

Contributing to Memvid

Thank you for your interest in contributing to Memvid! We welcome contributions from everyone.

Getting Started

Prerequisites

  • Rust 1.85.0+ — Install from rustup.rs
  • Git — For version control

Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

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

  3. Build the project:

    cargo build

  4. Run tests:

    cargo test

Development Workflow

Creating a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Making Changes

  1. Write your code following the code style guidelines
  2. Add tests for new functionality
  3. Ensure all tests pass: cargo test
  4. Run clippy: cargo clippy
  5. Format code: cargo fmt

Committing

Write clear, concise commit messages:

git commit -m "feat: add support for XYZ"
git commit -m "fix: resolve issue with ABC"
git commit -m "docs: update README examples"

Submitting a Pull Request

  1. Push to your fork:

    git push origin feature/your-feature-name

  2. Open a Pull Request on GitHub

  3. Fill out the PR template completely

  4. Wait for review and address feedback

Code Style

Rust Guidelines

  • Follow standard Rust idioms and conventions
  • Use rustfmt for formatting (cargo fmt)
  • Use clippy for linting (cargo clippy). We maintain a zero-warning policy.
  • Prefer explicit types for public APIs
  • Use thiserror for error definitions

Linting & Safety

We enforce strict linting to ensure safety and portability:

  1. Zero Warnings: CI will fail on any warning. Run cargo clippy --workspace --all-targets -- -D warnings locally.
  2. No Panics: unwrap() and expect() are denied in library code. Use Result propagation (?) or graceful error handling. They are allowed in tests/.
  3. No Truncation: cast_possible_truncation is denied. Use try_from when converting u64 to usize/u32.
  4. Exceptions: We allow pragmatic lints (e.g., cast_precision_loss for ML math) in src/lib.rs. Do not add global #![allow] without discussion.

Documentation

  • Add doc comments (///) to all public functions, structs, and modules
  • Include examples in doc comments where helpful
  • Keep comments concise and up-to-date

Testing

  • Write unit tests for new functionality
  • Place tests in the same file using #[cfg(test)] module
  • Integration tests go in the tests/ directory
  • Aim for high coverage of edge cases

Project Structure

memvid/
├── src/              # Source code
│   ├── lib.rs        # Public API
│   ├── memvid/       # Core implementation
│   ├── io/           # File I/O
│   └── types/        # Type definitions
├── tests/            # Integration tests
├── examples/         # Example code
├── benchmarks/       # Benchmarks
└── data/             # Required data files

Feature Flags

When adding new functionality, consider if it should be behind a feature flag:

[features]
my_feature = ["dep:some-dependency"]

This keeps the default build lean and fast.

Reporting Issues

When reporting bugs, please include:

  • Rust version (rustc --version)
  • Operating system
  • Memvid version
  • Minimal code to reproduce
  • Expected vs actual behavior

Translations

Interested in translating Memvid's documentation? See Contributing Translations for guidelines on translating the README and other documentation.

Getting Help

Recognition

Contributors are:

  • Listed in release notes
  • Part of the Memvid community

Thank you for making Memvid better!