2.8 KiB

Raw Blame History

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.9
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/your-org/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

Fork the repo and create a feature branch (feat/..., fix/..., docs/...)
Write clear commit messages (e.g., fix(query): handle null vector in dense_fp32)
Ensure tests pass & linter is clean
Open a Pull Request to main
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!

2.8 KiB Raw Blame History