pgContext Contributor Guide

Welcome to the pgContext Contributor Guide! We are thrilled to have you here. pgContext is developed as a modern Rust 2024 Cargo workspace featuring a tight PostgreSQL integration layer alongside highly reusable pure Rust crates.

Whether you’re fixing bugs, optimizing vector operations, or simply looking to understand our architecture, these guides will help you get started safely and quickly.

Guides

Local Setup

Install the pinned Rust toolchain from rust-toolchain.toml, then run the workspace gates:

cargo fmt --check
cargo clippy --workspace --exclude context-pg --all-targets --all-features -- -D warnings
cargo clippy -p context-pg --all-targets --features pg17 -- -D warnings
cargo test --workspace --exclude context-pg --all-features
cargo check -p context-pg --features pg17
scripts/run-v1-pgrx-tests.sh
cargo pgrx schema -p context-pg pg17 --out /tmp/pgcontext--0.1.0.generated.sql
scripts/check-extension-sql-artifact.sh --pg-major 17
scripts/check-hnsw-vacuum.sh
scripts/check-hnsw-restart.sh
cargo doc --workspace --no-deps
scripts/check-parity-matrix.sh
tests/shell/check_parity_matrix_smoke.sh
tests/shell/run_benchmark_report_smoke.sh
tests/shell/run_release_artifact_report_smoke.sh
tests/shell/check_extension_sql_artifact_smoke.sh
tests/shell/run_security_review_report_smoke.sh
tests/shell/run_postgres_matrix_gates_smoke.sh
scripts/check-source-hygiene.sh
scripts/check-hnsw-callback-guards.sh
tests/shell/check_hnsw_callback_guards_smoke.sh
scripts/run-unsafe-hardening-report.sh --pg-major 17 --plan
tests/shell/run_unsafe_hardening_report_smoke.sh

The PostgreSQL adapter is checked separately because pgrx crates link against PostgreSQL extension symbols instead of a normal host test binary. SQL-facing behavior should use pgrx or SQL regression tests once the relevant facade exists.

Supply-chain gates are part of CI:

cargo audit
cargo deny check
scripts/run-supply-chain-report.sh

Dependency Policy

Do not add dependencies casually. New dependency additions must use the repository safety wrapper for package-manager install or add commands, such as sfw cargo add crate-name. Routine commands like cargo test, cargo build, and cargo doc run normally.

Each new dependency needs a clear reason, a license/advisory review, and a small commit that makes the resulting graph auditable.

Development Expectations

Every milestone starts with tests that define the behavior. Keep PostgreSQL integration in context-pg; reusable algorithms and domain types belong in the pure Rust crates. Update public documentation and rustdoc in the same change as behavioral code.

Unsafe code is denied by default. Only context-core, context-pg, and context-storage may opt in when PostgreSQL FFI or validated mmap work requires it, and every unsafe block must have a local SAFETY: explanation.