Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
98 lines (75 loc) · 3.9 KB

CONTRIBUTING.md

File metadata and controls

98 lines (75 loc) · 3.9 KB
Raw

Contributing to SQLPage

Setup and build

Install stable Rust and Node.js (see CI for the Node version), then run this command from a checkout:

npm run build:rust

This installs locked npm dependencies, builds browser assets, and creates target/debug/sqlpage. Afterwards, use cargo build for Rust changes and npm run build for frontend changes. Add -- --release to npm run build:rust for a release build.

Default builds require a system ODBC driver manager. On Linux and macOS, --features odbc-static bundles unixODBC, but database-specific drivers must still be installed separately. Windows uses its system ODBC driver manager. Published crates include browser assets and do not require Node.js.

Optional: Nix dev shell

If you have Nix with flakes enabled, nix develop provides the tools above at the versions CI uses. With direnv, direnv allow enters the shell automatically when you enter the directory. When Nix is not installed, direnv leaves your environment unchanged.

Command What it runs
nix fmt rustfmt, Biome, and nixfmt
nix flake check formatting, plus the flake's own version assertions
nix run .#lint-rust cargo fmt --check and cargo clippy
nix run .#test-rust the Rust test suites
nix run .#test-browser the Playwright suites
nix run .#test-examples one example's Hurl suite
nix build .#odbc-drivers an odbcinst.ini; point ODBCSYSINI at it for the ODBC tests

Validation

For Rust changes:

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test

For frontend changes:

npm run format
npm test
npm run build

Keep formatting scoped to changed files. npm test checks formatting, lint, types, and frontend unit tests. Dynamic frontend changes also need Playwright:

cd tests/end-to-end
npx playwright install --with-deps --only-shell chromium
npm test

Playwright starts its servers on free ports. Set SQLPAGE_BINARY to use an already built executable. Component suites use fixtures/<suite>/{index.sql,test.ts} and import the shared fixture.ts harness; root-level *.spec.ts files cover the official site. For examples with test.hurl, run scripts/test-examples-hurl.sh '<example-path>' from the repository root.

Integration tests use the shared request helpers in tests/common to exercise production routes and middleware and drain request pools.

Rust tests default to in-memory SQLite; DATABASE_URL selects another database. For example:

docker compose up --wait mssql
DATABASE_URL='mssql://root:Password123!@localhost/sqlpage' cargo test

Use the CI matrix for supported backends, connection strings, and driver setup. On Linux and macOS, cargo test --features odbc-static matches CI's driver-manager linking. Oracle and DuckDB need host ODBC drivers even when the database runs in a container. For local Oracle runs, add -- --test-threads=2 to avoid overwhelming the listener. Check affected matrix results for SQL execution changes; SQLite alone cannot establish portability.

Submitting a change

Follow nearby code and tests, add regression coverage, and describe the resulting behavior and validation in the pull request. Keep changes and formatting focused. Architectural constraints and documentation maintenance rules are in AGENTS.md.

User documentation lives in the official-site SQL pages and migrations. Edit existing documentation in place: deployment recreates the site database. Use nearby entries as examples rather than copying schemas into this guide. Update configuration.md for configuration changes and CHANGELOG.md for user-visible changes in an unreleased version.