Contributing

Thank you for your interest in contributing to GalaxDB. We welcome bug reports, feature requests, documentation improvements, and code contributions.

Before starting, read the Code of Conduct. For large changes, open an issue first to discuss the approach.

Development Setup

Requirements: Rust stable 1.80+, Python 3.9+, maturin

git clone https://github.com/zentrix-innovative-labs/galaxdb
cd galaxdb

# Build and test the Rust workspace
cargo build --workspace
cargo test --workspace --exclude galaxdb-python --lib

# Build the Python wheel (for Python client tests)
pip install maturin
maturin develop -m galaxdb-python/Cargo.toml

# Run Python tests
pip install pytest pyarrow psycopg2-binary sqlalchemy
pytest galaxdb-python/tests/python/ -v

Engineering Rules

These rules are enforced by CI and will cause your PR to fail if violated:

1. No mocks in production code paths. Mocks belong in #[cfg(test)] blocks only. Production code must never carry a mock, stub, fake, or fallback that silently substitutes synthetic behavior.
2. No silent fallbacks. If a real implementation fails (model load, KMS decrypt, sidecar crash past retry budget), surface a typed error to the caller. No logging-and-returning-fake-data.
3. No task ticked without real implementation. Tests must exercise real code against real infrastructure.
4. No vendor lock-in. No aws-sdk-*, google-cloud-*, or azure_* dependencies. External services are pluggable via trait.
5. Cross-platform. Code must compile and pass tests on macOS, Linux, and Windows. #[cfg(target_os = "linux")] is acceptable only for Linux-specific optimizations with a fallback.
6. No faked benchmarks. Every benchmark number must be reproducible from a named command against a named dataset on named hardware.

CI Gates

Run these locally before opening a PR:

# 1. Check for mocks in production code
bash scripts/grep-for-mocks.sh

# 2. Check task tracker consistency
bash scripts/check-tasks-no-stub-ticks.sh

# 3. Check dependency licenses and security
cargo deny check

# 4. Run the full test suite
cargo test --workspace --exclude galaxdb-python --lib

# 5. Run chaos tests
cargo run --release -p galaxdb-chaos-tests

All five gates must exit 0 before a PR can be merged.

Pull Request Process

1. Fork the repo and create a branch from main
2. Make your changes with tests
3. Run cargo test --workspace --exclude galaxdb-python --lib — all tests must pass
4. Run the three CI gates above — all must exit 0
5. Open a PR against main with a clear description of what changed and why
6. A maintainer will review within 5 business days

PR title format: type(scope): description

feat(storage): add zone-map pruning for TEXT columns
fix(hnsw): correct recall calculation for ef_search < k
docs(python): add training API examples
test(chaos): add disk-full recovery scenario
perf(wal): reduce fsync latency with io_uring

Reporting Bugs

Open a GitHub issue with:

• GalaxDB version: cargo pkgid galaxdb-server | cut -d# -f2
• OS and architecture
• Minimal reproduction case (SQL or Python code)
• Expected vs actual behaviour
• Relevant log output