Contributing

Welcome Contributors!

Thank you for considering contributing to Zvec! Whether you’re fixing a bug, adding a feature, improving documentation, or helping others, your contribution helps make Zvec better for everyone.

By participating, you agree to abide by our Code of Conduct. Please be respectful, collaborative, and inclusive.

Ways to Contribute

Report Bugs

Found an issue? Report it on GitHub Issues

Suggest Features

Have an idea? Share it in Discussions

Fix Bugs

Browse open issues labeled good first issue

Improve Docs

Documentation improvements are always welcome!

Development Setup

Follow these steps to set up your development environment.

Prerequisites

Ensure you have:

Python 3.10 - 3.12
CMake ≥ 3.26, < 4.0
C++17-compatible compiler:
- Linux: g++-11 or later
- macOS: Xcode Command Line Tools (Apple Clang)

Verify versions:

python --version
cmake --version
g++ --version  # or clang++ --version on macOS

Clone the Repository

Clone with submodules:

git clone --recursive https://github.com/alibaba/zvec.git
cd zvec

If you forgot --recursive, initialize submodules:

git submodule update --init --recursive

Install Pre-commit Hooks

Set up pre-commit hooks to automatically check code quality:

pip install pre-commit
pre-commit install

This ensures your commits meet coding standards before pushing.

Build and Install (Editable Mode)

Install Zvec in editable mode with development dependencies:

pip install -e ".[dev]"

This command:

Installs Zvec in development mode
Compiles the C++ extension in-place
Installs dev dependencies (pytest, ruff, etc.)

Verify Installation

python -c "import zvec; print('Success!')"

If successful, you’re ready to develop!

Testing

Run All Tests

Run the full test suite:

pytest python/tests/ -v

Run Specific Tests

# Test a specific file
pytest python/tests/test_collection.py -v

# Test a specific function
pytest python/tests/test_collection.py::test_insert -v

Run with Coverage

Generate a coverage report:

pytest python/tests/ --cov=zvec --cov-report=term-missing

Aim for at least 80% code coverage when adding new features.

C++ Tests

If you’re working on C++ code, build and run C++ tests:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
make
ctest --verbose

Code Style and Linting

Python Code Style

Zvec uses Ruff for linting and formatting. Check for issues:

ruff check python/

Auto-fix issues:

ruff check --fix python/

Format code:

ruff format python/

C++ Code Style

For C++ contributions:

Follow existing code style in the repository
Use meaningful variable and function names
Add comments for complex logic
Keep functions focused and modular

Pre-commit hooks will automatically check Python style before commits.

Build Customization

Control the build process with environment variables:

Option	How to Set	Description
Build Type	`CMAKE_BUILD_TYPE=Debug`	`Debug`, `Release`, or `Coverage`
Generator	`CMAKE_GENERATOR="Unix Makefiles"`	Default: `Ninja`; use `Make` if preferred
AVX-512	`ENABLE_SKYLAKE_AVX512=ON`	Enable AVX-512 optimizations (x86_64 only)

Example: Debug build with Make:

CMAKE_BUILD_TYPE=Debug CMAKE_GENERATOR="Unix Makefiles" pip install -v -e .

Coverage Build

For C++ code coverage with gcov/lcov:

CMAKE_BUILD_TYPE=Coverage pip install -v -e .
# Run tests
pytest python/tests/
# Generate coverage report
lcov --capture --directory build --output-file coverage.info
genhtml coverage.info --output-directory coverage_html

Submitting Changes

Follow these steps to submit your contribution:

1. Create a Feature Branch

Branch from main using a descriptive name:

git checkout -b feat/add-sparse-vector-support
# or
git checkout -b fix/query-dimension-mismatch
# or
git checkout -b docs/improve-quickstart

Branch naming conventions:

feat/ - New features
fix/ - Bug fixes
docs/ - Documentation changes
refactor/ - Code refactoring
test/ - Test additions/improvements

2. Make Your Changes

Write clear, focused code
Add tests for new functionality
Update documentation as needed
Follow existing code style

3. Write Clear Commit Messages

Use descriptive commit messages:

git commit -m "feat(query): add support for sparse vector queries"
git commit -m "fix(insert): handle null vectors in VECTOR_FP32"
git commit -m "docs(quickstart): clarify installation steps"

Format: type(scope): description Types: feat, fix, docs, refactor, test, chore

4. Run Tests and Linters

Before pushing:

# Run tests
pytest python/tests/ -v

# Check linting
ruff check python/

# Format code
ruff format python/

5. Push Your Branch

git push origin feat/add-sparse-vector-support

6. Open a Pull Request

Go to GitHub and open a Pull Request:

Click “Compare & pull request”
Write a descriptive title and description
Link related issues (e.g., “Closes #123”)
Request review from maintainers

PR checklist:

Ensure all tests pass and code is properly formatted before submitting your PR.

Pull Request Guidelines

What to Include

Your PR should include: ✅ Test coverage for new behavior
✅ Documentation updates (if adding features)
✅ Clear reasoning for non-obvious design choices
✅ Reference to related issues

PR Review Process

Automated checks run (CI, linting, tests)
Maintainers review your code
Feedback and iteration - address review comments
Approval - maintainer approves PR
Merge - your contribution is merged!

Be patient during review. Maintainers may take time to respond, especially for large changes.

Documentation

User Guides

Documentation is built with Mintlify:

# Install Mintlify CLI
npm i -g mint

# Preview docs locally
cd docs
mint dev

# Open http://localhost:3000

Documentation source:

Location: docs/ directory
Format: MDX (Markdown + JSX)
Configuration: docs.json

API Reference

API docs are generated from docstrings. Follow Google style:

def query(self, vector: List[float], topk: int = 10) -> List[Dict]:
    """Query the collection for similar vectors.
    
    Args:
        vector: Query vector as a list of floats.
        topk: Number of results to return (default: 10).
    
    Returns:
        List of dicts with keys 'id' and 'score'.
    
    Raises:
        ValueError: If vector dimension doesn't match schema.
    
    Example:
        >>> results = collection.query([0.1, 0.2, 0.3], topk=5)
        >>> print(results[0]['id'])
        'doc_123'
    """
    pass

Community Guidelines

Getting Help

If you need help while contributing:

GitHub Discussions - Ask questions
Discord - Real-time chat
Existing Issues - Browse for similar problems

Reporting Security Issues

For security vulnerabilities, do not open a public issue. Instead:

Email: [email protected]
Provide detailed description and steps to reproduce
Allow time for maintainers to respond

Recognition

Contributors are recognized:

Listed in GitHub contributors
Mentioned in release notes (for significant contributions)
Eligible for Zvec swag (for major contributions)

Good First Issues

New to Zvec? Look for issues labeled:

good first issue - Beginner-friendly
help wanted - Community contributions welcome
documentation - Docs improvements

These are great starting points for your first contribution!

Code Review Best Practices

For Contributors

Keep PRs focused and small (easier to review)
Respond to feedback promptly and respectfully
Ask questions if feedback is unclear
Mark conversations as resolved after addressing

For Reviewers

Be constructive and respectful in feedback
Focus on code quality, not personal preferences
Explain why changes are suggested
Approve when satisfied with changes

Resources

GitHub Repository

Browse source code and issues

Contributing Guide

Full contributing guide on GitHub

Code of Conduct

Community guidelines

Discord Community

Join the conversation

Thank You!

Your contributions make Zvec better for everyone. Whether it’s a bug fix, a new feature, or improved documentation, we appreciate your effort and time.

✨ Thanks again for being part of Zvec! ✨

Additional Resources

​Welcome Contributors!

​Ways to Contribute

Report Bugs

Suggest Features

Fix Bugs

Improve Docs

​Development Setup

​Prerequisites

​Clone the Repository

​Install Pre-commit Hooks

​Build and Install (Editable Mode)

​Verify Installation

​Testing

​Run All Tests

​Run Specific Tests

​Run with Coverage

​C++ Tests

​Code Style and Linting

​Python Code Style

​C++ Code Style

​Build Customization

​Coverage Build

​Submitting Changes

​1. Create a Feature Branch

​2. Make Your Changes

​3. Write Clear Commit Messages

​4. Run Tests and Linters

​5. Push Your Branch

​6. Open a Pull Request

​Pull Request Guidelines

​What to Include

​PR Review Process

​Documentation

​User Guides

​API Reference

​Community Guidelines

​Getting Help

​Reporting Security Issues

​Recognition

​Good First Issues

​Code Review Best Practices

​For Contributors

​For Reviewers

​Resources

GitHub Repository

Contributing Guide

Code of Conduct

Discord Community

​Thank You!

Build docs developers (and LLMs) love

Welcome Contributors!

Ways to Contribute

Development Setup

Prerequisites

Clone the Repository

Install Pre-commit Hooks

Build and Install (Editable Mode)

Verify Installation

Testing

Run All Tests

Run Specific Tests

Run with Coverage

C++ Tests

Code Style and Linting

Python Code Style

C++ Code Style

Build Customization

Coverage Build

Submitting Changes

1. Create a Feature Branch

2. Make Your Changes

3. Write Clear Commit Messages

4. Run Tests and Linters

5. Push Your Branch

6. Open a Pull Request

Pull Request Guidelines

What to Include

PR Review Process

Documentation

User Guides

API Reference

Community Guidelines

Getting Help

Reporting Security Issues

Recognition

Good First Issues

Code Review Best Practices

For Contributors

For Reviewers

Resources

Thank You!