Skip to content

Latest commit

 

History

History
112 lines (79 loc) · 2.82 KB

CONTRIBUTING.md

File metadata and controls

112 lines (79 loc) · 2.82 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

Prerequisites

  • Python 3.10 - 3.12
  • 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!