Contributing to VelesDB

First off, thank you for considering contributing to VelesDB! It's people like you that make VelesDB such a great tool.

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Style Guidelines
• Release Process

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

• Use a clear and descriptive title
• Describe the exact steps to reproduce the problem
• Provide specific examples (code snippets, configuration files)
• Describe the behavior you observed and what you expected
• Include your environment details (OS, Rust version, VelesDB version)

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

• Use a clear and descriptive title
• Provide a detailed description of the proposed enhancement
• Explain why this enhancement would be useful
• List any alternatives you've considered

Your First Code Contribution

Unsure where to begin? Look for issues labeled:

• good first issue - Simple issues perfect for newcomers
• help wanted - Issues where we need community help
• documentation - Documentation improvements

Pull Requests

This project follows Git Flow. Feature and fix branches must target develop, not main.

Branch prefix	Target	Examples
feature/*, feat/*	develop	feature/amazing-feature
fix/*, bugfix/*	develop	fix/crash-on-empty-index
refactor/*, chore/*, ci/*, docs/*, style/*, perf/*, test/*, build/*	develop	docs/update-api-guide
release/*, hotfix/*, support/*	main	release/1.2.0

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (cargo test)
5. Run lints (cargo clippy)
6. Format code (cargo fmt)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request targeting develop (not main)

Architecture Quick Start

New to the codebase? Start with these documents (in order):

1. Project Structure — Workspace layout, crate responsibilities (~15 min)
2. Architecture — 3-layer design (Client, API, Core), data flow (~30 min)
3. Concurrency Model — Lock ordering, shard strategy, deadlock prevention (~20 min)
4. Storage Format — On-disk layout, WAL, mmap (~15 min)
5. Soundness — Unsafe code audit with invariant proofs (reference)

Workspace Crate Map

Crate	Purpose
velesdb-core	Core engine: HNSW, SIMD, VelesQL, collections, storage
velesdb-server	Axum REST API server (47 endpoints, OpenAPI optional)
velesdb-cli	Interactive REPL for VelesQL
velesdb-python	PyO3 bindings with NumPy support
velesdb-wasm	Browser-side vector search (no persistence feature)
velesdb-mobile	iOS/Android bindings via UniFFI
velesdb-migrate	Schema/data migration tooling
velesdb-memory	MCP agent-memory server (MemoryService wedge: remember/recall/why)
velesdb-node	Node.js binding of the memory wedge (napi-rs; @wiscale/velesdb-memory-node)
tauri-plugin-velesdb	Tauri desktop integration

Quality Gates

All new/modified code must satisfy these limits (enforced by Codacy and CI):

Metric	Limit	Enforcement
Cyclomatic complexity	<= 8 per function	Codacy
Function NLOC	<= 50 lines	Codacy
File NLOC	<= 500 lines	Code review
Code duplication	< 2%	jscpd
Unsafe blocks	Must have // SAFETY: comment	CI (verify_unsafe_safety_template.py)
TODO format	// TODO(EPIC-XXX): only	CI (check-todo-annotations.py)
.unwrap()	Forbidden in production code	Code review
Recall@10	>= 0.95 (if search path modified)	CI + local validation

Concurrency Rules

• Use parking_lot::RwLock / Mutex (never std::sync — no poisoning, no .unwrap() on locks)
• Follow lock ordering documented in CONCURRENCY_MODEL.md
• Tests MUST run single-threaded: --test-threads=1 (file system isolation)

Pre-Push Validation

Run this sequence before every push (CI runs on every PR — running it locally first avoids red pipelines and wasted CI minutes):

# 1. Format
cargo fmt --all

# 2. Lint (strict — mirrors CI)
cargo clippy --workspace --all-targets --features persistence,gpu,update-check \
  --exclude velesdb-python -- -D warnings -D clippy::pedantic

# 3. Tests
cargo test -p velesdb-core --features persistence -- --test-threads=1

# 4. (If search path modified) Recall gate
cargo test -p velesdb-core --features persistence test_recall -- --test-threads=1

# 5. Feature gate check
cargo check --no-default-features
cargo check -p velesdb-wasm --no-default-features --target wasm32-unknown-unknown

# 6. (Optional) Codacy CLI — run from the repo root
codacy-cli analyze
# Windows: prefix with `wsl -- bash -c "cd $(wslpath -a .) && ..."` if the CLI runs under WSL.

Or use the local CI script: .\scripts\local-ci.ps1 (Full) or .\scripts\local-ci.ps1 -Quick (fmt + clippy only).

Git hooks are provided in .githooks/ — activate with: git config core.hooksPath .githooks

Note (SSH pushes): the pre-push hook runs the full validation (~15 min) while git already holds the connection to GitHub open; if that SSH connection dies in the meantime, git push exits 141 (SIGPIPE) with no error message right after the validation passes. Pushing over HTTPS is immune (the ref advertisement and the pack upload are independent requests):

git config remote.origin.pushurl https://github.com/cyberlife-coder/VelesDB.git
git config credential.helper '!gh auth git-credential'

Development Setup

Prerequisites

• Rust 1.89+ (stable) — enforced as MSRV (required for avx512vpopcntdq target_feature stabilized in 1.89; see crates/velesdb-core/src/simd_native/x86_avx512.rs)
• Docker (optional, for integration tests)

Building from Source

# Clone the repository (replace cyberlife-coder with your fork if contributing via PR)
git clone https://github.com/cyberlife-coder/VelesDB.git
cd VelesDB

# Build the project
cargo build --workspace

# Run tests (single-threaded — required for file system isolation)
cargo test --workspace --features persistence,gpu,update-check \
  --exclude velesdb-python -- --test-threads=1

# Lint (strict — mirrors CI)
cargo clippy --workspace --all-targets --features persistence,gpu,update-check \
  --exclude velesdb-python -- -D warnings -D clippy::pedantic

# Run the server locally
cargo run --bin velesdb-server -- --data-dir ./data

Running Benchmarks

cargo bench -p velesdb-core --features internal-bench -- --noplot

Pull Request Process

1. Ensure all tests pass - Run cargo test --workspace --features persistence,gpu,update-check --exclude velesdb-python -- --test-threads=1 before submitting
2. Update documentation - If you're adding new features, update the relevant docs
3. Follow the style guidelines - Run cargo fmt and cargo clippy
4. Write meaningful commit messages - Follow conventional commits format
5. Keep PRs focused - One feature or fix per PR
6. Be responsive - Address review feedback promptly

Commit Message Format

We follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• perf: Performance improvements
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(search): add hybrid search support
fix(storage): resolve mmap alignment issue on ARM
docs(readme): update quick start guide

Style Guidelines

Rust Code Style

• Follow the Rust API Guidelines
• Use rustfmt for formatting (default configuration)
• Use clippy for linting (fix all warnings)
• Write documentation for public APIs
• Keep functions under 50 lines when possible
• Prefer composition over inheritance

Documentation Style

• Use clear, concise language
• Include code examples where appropriate
• Keep README focused on getting started
• Put detailed docs in the /docs folder

Contributor License Agreement (CLA)

By submitting a pull request, you agree to the VelesDB CLA: you grant cyberlife-coder a perpetual, worldwide, non-exclusive, royalty-free license to use, modify, and distribute your contribution under the terms of the VelesDB Core License 1.0 or any future license chosen by the project.

This is required to allow VelesDB to offer commercial licensing alongside the source-available version. All past contributions are covered retroactively.

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md — full list with PR links
• Release notes for each version they contributed to
• Our Discord community

Release Process

VelesDB uses 3 simplified GitHub Actions workflows:

Workflow	Purpose
ci.yml	Tests, lint, security
release.yml	Full publish (binaries, crates.io, PyPI, npm)
bench-regression.yml	Benchmarks

Publishing a release

# 1. Bump every manifest in lock-step
python3 scripts/bump_version.py <X.Y.Z>
python3 scripts/check-version-sync.py   # every policed manifest must align
python scripts/check-promise-contract.py # 19 claims must pass
cargo update --workspace                 # refresh Cargo.lock

# 2. Open release/<vX.Y.Z> -> main, wait for ALL CI green on the merge commit
# 3. Tag from main (NEVER push the tag before CI Success on main HEAD)
git checkout main && git pull origin main
git tag -a v<X.Y.Z> -m "v<X.Y.Z> -- <one-line summary>"
git push origin main --tags

The release.yml workflow automatically publishes to:

• GitHub Releases (binaries)
• crates.io
• PyPI
• npm

📖 Full guide: docs/contributing/RELEASE.md

---

Thank you for contributing to VelesDB! 🦀