Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (126 loc) · 5.65 KB

CONTRIBUTING.md

File metadata and controls

175 lines (126 loc) · 5.65 KB
Raw

Contributing to SQE

Thank you for your interest in contributing to the Sovereign Query Engine.

Reporting Issues

Open a GitHub issue for bugs, feature requests, or questions. Include:

  • Bug reports: Steps to reproduce, expected vs actual behavior, SQE version, OS, Rust version
  • Feature requests: What you want, why you need it, and how you think it should work
  • Questions: Check existing issues and docs first. If the answer is not there, open an issue

How to Contribute

  1. Fork the repository and create a feature branch from main
  2. Never push directly to main -- all changes go through pull requests
  3. One logical change per PR -- keep pull requests focused and reviewable

Branch naming

Use a prefix that describes the type of change:

  • feat/ -- new feature or capability
  • fix/ -- bug fix
  • refactor/ -- code restructuring without behavior change
  • docs/ -- documentation only
  • test/ -- adding or updating tests
  • perf/ -- performance improvement

Workflow

# Fork and clone
git clone https://github.com/YOUR_USERNAME/sqe.git
cd sqe

# Create a feature branch
git checkout -b feat/my-feature

# Make changes, then commit
git add -p
git commit -m "feat: add my feature"

# Push and open a pull request
git push -u origin feat/my-feature

Then open a pull request on GitHub against main.

Commit Format

We use Conventional Commits:

  • feat: -- new feature or capability
  • fix: -- bug fix
  • docs: -- documentation only
  • chore: -- maintenance, dependencies, CI
  • refactor: -- code restructuring without behavior change
  • test: -- adding or updating tests
  • perf: -- performance improvement

Examples:

feat: add AWS Glue catalog backend
fix: handle expired JWT tokens in bearer auth
docs: update pluggable catalogs design spec

Pre-commit hooks

This repo ships a pre-commit config that mirrors Aikido's .pre secret-scan gate (aikido-secret-scan: gitleaks against .gitleaks.toml) plus a few cheap file checks. The hook is already installed in many local clones; without .pre-commit-config.yaml it used to skip.

# once per clone (skip if `git config core.hooksPath` is already set;
# this repo's git template installs the pre-commit wrapper into .git/hooks)
pre-commit install

# against staged files (also runs as the git pre-commit hook)
pre-commit run
make pre-commit

# against the whole tree
pre-commit run --all-files

The gitleaks hook compiles the pinned v8.30.1 tag (same 8.30.x line as the aikido-tools image) rather than calling a system gitleaks. Allowlists live in .gitleaks.toml, not in the hook.

Semgrep, grype, trivy, and syft stay in CI. They need the aikido-tools image and are too heavy for a commit hook. The full-history gitleaks pass is schedule-only in CI (aikido-secret-scan-history).

Code Style

SQE follows standard Rust conventions:

  • Formatting: Run cargo fmt --all before committing. CI enforces this.
  • Linting: cargo clippy --all-targets --all-features -- -D warnings must pass with zero warnings.
  • No unsafe code without a comment explaining why it is necessary.
  • Error handling: Use Result and the project's error types. No .unwrap() in production code.

Testing Requirements

All contributions must include appropriate tests. Before submitting a PR:

# Format check
cargo fmt --all -- --check

# Static analysis (must pass with zero warnings)
cargo clippy --all-targets --all-features -- -D warnings

# Unit tests
cargo test --all

# Security advisory scan
cargo audit

# Dependency policy check
cargo deny check advisories

# Integration tests (brings up its own Polaris + RustFS stack via Docker)
make test-integration

The integration suites have no CI equivalent (issue #387: the shared runners have no working docker-in-docker sidecar, so those jobs were removed rather than left permanently yellow). Run them locally before merging anything that touches the read or write path:

make test-integration                             # full suite
make test-integration FILTER=test_ctas_roundtrip  # one test by substring
make test-distributed                             # coordinator + 2 workers
make test-integration-down                        # tear the stack back down

The stack is deliberately left running afterwards: bootstrap is idempotent, so a rerun skips the bring-up. A preflight names any container holding one of the fixed host ports, which is the usual failure when a bench or parity rig is still up from an earlier session.

Test Suite Overview

Suite Location Requires
Unit tests crates/*/src/ (#[cfg(test)] modules) Nothing
Integration tests crates/sqe-coordinator/tests/ make test-integration (Docker)
Access-control e2e crates/sqe-coordinator/tests/it/ make test-access-control (Ranger stack)
Quickstart scenarios quickstart/*/run.sh --check scripts/test.sh scenario all
E2E tests scripts/e2e-test.sh Full stack
Benchmarks sqe-bench crate Polaris + S3 stack

Code Review

  • All PRs require at least one review before merge
  • CI must pass (fmt, clippy, tests, audit, deny)
  • Benchmark-sensitive changes should include benchmark results

Documentation

If your change affects user-facing behavior, update the relevant docs. Key files:

  • README.md -- roadmap checklist and feature overview
  • docs/site/compare/features.md -- detailed feature comparison
  • docs/site/compare/trino-compatibility.md -- Trino SQL compatibility matrix

License

By contributing to SQE, you agree that your contributions will be licensed under the Apache License 2.0.