Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (81 loc) · 2.92 KB

CONTRIBUTING.md

File metadata and controls

115 lines (81 loc) · 2.92 KB

Contributing to Zvec

First off, thank you for considering contributing to Zvec! 🙌
Whether you're reporting a bug, proposing a feature, improving documentation, or submitting code — every contribution helps make Zvec better.

Code of Conduct

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

Development Setup

Tip

Linux is the recommended environment for development and performance benchmarking.

Prerequisites

  • Python 3.10 - 3.14
  • CMake ≥ 3.26, < 4.0 (cmake --version)
  • A C++17-compatible compiler (e.g., g++-11+, clang++, Apple Clang on macOS)

Clone & Initialize

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

💡 Tip

  • Forgot --recursive? Run: 
    git submodule update --init --recursive
  • Set up pre-commit hooks: 
    pip install pre-commit && pre-commit install

Build from Source (Editable Install)

pip install -e ".[dev]"
# This installs dev dependencies (pytest, ruff, etc.) and builds the C++ extension in-place

✅ Verify:

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

Testing

Run All Tests

pytest python/tests/ -v

Run with Coverage (Debug/CI)

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

🔎 See full rules in [tool.ruff] section of pyproject.toml.

Build Customization

You can control build behavior via environment variables or pyproject.toml:

Option How to Set Description
Build Type CMAKE_BUILD_TYPE=Debug Debug, Release, or Coverage (for gcov/lcov)
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 + Make):

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

Submitting Changes

  1. Fork the repo and create a feature branch (feat/..., fix/..., docs/...)
  2. Write clear commit messages (e.g., fix(query): handle null vector in dense_fp32)
  3. Ensure tests pass & linter is clean
  4. Open a Pull Request to main
  5. Link related issue (e.g., Closes #123)

✅ PRs should include:

  • Test coverage for new behavior
  • Updates to documentation (if applicable)
  • Reasoning behind non-obvious design choices

Documentation

  • User guides: docs/ (built with MkDocs)
  • API reference: generated from docstrings (follow Google style)
  • Build & deploy: mkdocs serve / mkdocs build

Need Help

  • Browse existing issues
  • For sensitive/security issues: email zvec@alibaba-inc.com

✨ Thanks again for being part of Zvec!