Contributing & Code Review

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• GATE_1_COMPLETE.md
• GATE_2_BLOCKED.md
• scripts/pre-release-check.sh
• fuzz/FUZZING_STRATEGY.md

Contributing to EdgeVec requires adherence to a rigorous "Nvidia Grade" development protocol where correctness, memory safety, and verification are the primary objectives. The project enforces a "hostile default" mindset, assuming code will break in production unless proven otherwise through extensive multi-layer testing and formal architectural gates. Sources: CONTRIBUTING.md:3-8, GATE_1_COMPLETE.md:200-210

This documentation covers the mandatory practices for submitting code, the tiered verification pyramid, and the hostile review process that every contribution must clear before being merged or released. Sources: CONTRIBUTING.md:10-15, scripts/pre-release-check.sh:10-15

Core Development Principles

EdgeVec development is governed by three non-negotiable pillars:

• Test-First Development (TDD): Features must begin with test definitions that establish expected behavior before implementation starts. Sources: CONTRIBUTING.md:21-25
• Correctness Over Convenience: Performance claims and fast algorithms are secondary to provable correctness. This includes documented safety proofs for any unsafe code and property-based verification for all algorithms. Sources: CONTRIBUTING.md:38-43
• Hostile Default: Developers must explicitly handle all error paths and design for failure modes. Silent failures and assumptions about input validity are strictly prohibited. Sources: CONTRIBUTING.md:45-50

Forbidden Patterns

The following patterns are strictly banned in the library codebase:

• Panics in Library Code: Never use unwrap(), expect(), or assert! in library modules (allowed only in tests, examples, or build scripts). Sources: CONTRIBUTING.md:56-65, GATE_2_BLOCKED.md:24-25
• Unjustified unsafe: Every unsafe block must include a safety proof and a reference to the review that approved it. Sources: CONTRIBUTING.md:86-95
• Magic Numbers: All constants must be named and cited (e.g., referencing a specific section of a paper). Sources: CONTRIBUTING.md:110-115

Verification Pyramid

EdgeVec utilizes a multi-layered testing strategy, referred to as the "Nvidia Grade" standard, to ensure system integrity across different environments. Sources: GATE_1_COMPLETE.md:73-85, CONTRIBUTING.md:175-185

Testing Layers

Layer	Count/Type	Requirement
E2E Tests	5	Browser automation and end-to-end workflows.
Integration	6	Persistence and search cross-component workflows.
Recall	1	95% threshold on SIFT dataset for ANN accuracy.
Property-Based	8	Invariants and serialization consistency via proptest.
Fuzz + Miri	4 Targets	Memory safety and adversarial input handling.
Unit Tests	200+	100% coverage for all public APIs.

Sources: CONTRIBUTING.md:175-185, GATE_1_COMPLETE.md:73-85

Fuzzing Strategy

Fuzzing is a mandatory quality gate for security-sensitive operations. The project uses cargo-fuzz to target components like binary quantization, header parsing, and WAL (Write-Ahead Log) replay. Sources: fuzz/FUZZING_STRATEGY.md:10-25

Code Review & Quality Gates

The project employs Quality Gates to manage transitions between development phases. These are enforced by a HOSTILE_REVIEWER authority. Sources: GATE_1_COMPLETE.md:3-8, GATE_2_BLOCKED.md:3-8

The Hostile Review Process

Every Pull Request (PR) undergoes maximum scrutiny focusing on:

1. Safety: Preservation of invariants and lack of undefined behavior.
2. Performance: Adherence to established performance budgets.
3. Verification: Comprehensiveness of the "Nvidia Grade" test suite.
4. Structure: Consistency of data layouts and versioning.

Sources: CONTRIBUTING.md:218-225, GATE_2_BLOCKED.md:20-30

Pre-Release Validation

Before any code can proceed to a release branch, the pre-release-check.sh script must pass locally. This script simulates the CI environment. Sources: scripts/pre-release-check.sh:1-15

Release Protocol

The release process follows a four-phase validation checklist to prevent post-release incidents:

1. Local Code Quality: Formatting, Clippy lints, and documentation warnings.
2. CI Simulation: Full test suite execution with specific RUSTFLAGS and property test cases.
3. WASM Validation: Compilation for wasm32-unknown-unknown and bundle size verification.
4. Dry Run: Execution of cargo publish --dry-run and npm pack --dry-run.

Sources: scripts/pre-release-check.sh:80-180, CONTRIBUTING.md:290-300

Emergency Procedures

If a release fails despite these gates, the project maintains ROLLBACK_PROCEDURES.md for incident response. Sources: CONTRIBUTING.md:300-305

Summary: The contributing and code review process in EdgeVec is designed to eliminate unknowns and prevent regression. By enforcing architectural gates (Gate 1 for Architecture, Gate 2 for Implementation) and a tiered verification pyramid, the project ensures that all contributions maintain the high standards required for an embedded vector database. Sources: GATE_1_COMPLETE.md:120-130, GATE_2_BLOCKED.md:35-45