Contributing

Dev setup

SeeKi is one Rust binary that embeds a Svelte frontend. You need both toolchains on your machine, but only once.

Prerequisites

• Rust — edition 2024, so rustc 1.85 or newer. Install via rustup.
• Node runtime — Bun is the default; npm works as a fallback. The frontend has no lockfile preference, both produce the same tree.
• A PostgreSQL you can point at. The Chinook sample database is enough.

First build

# clone and enter the repo
git clone https://github.com/Kiriketsuki/seeKi.git
cd seeKi

# install frontend deps
cd frontend
bun install      # or: npm install
bun run build    # or: npm run build
cd ..

# build and run the binary
cargo run

The first launch opens the setup wizard — point it at your PostgreSQL, then the grid is live at http://127.0.0.1:3141.

Iteration loop

• cargo check — fastest feedback on Rust edits.
• cargo test — run before opening a PR.
• cargo clippy — lints the CI enforces. Warnings are errors on CI.
• cargo fmt — formatting is checked too.
• cd frontend && bun run dev — hot-reload the Svelte side while the Rust server runs.

Branch naming

Every branch starts with a type prefix, lowercase and kebab-cased. The GitHub automation creates branches in this shape for labelled issues; human branches should match.

Branches created from issues include the issue number: feat/42-saved-views.

Conventional commits

Commit subjects follow Conventional Commits. Same prefixes as the branch types, with optional scope.

<type>[(scope)]: <description>

[optional body]

[optional footer(s)]

Good subjects are imperative, sentence-case, and fit on one line under 72 characters. Examples pulled from main:

• fix(ci): repair version-bump workflow YAML parse error
• epic: End-to-End QA (#32)
• chore: Redesign logo, favicon, and brand mark (#54)
• feat: scaffold SeeKi project structure

The body is where the why goes. If the change is obvious from the diff, skip the body — do not restate the subject.

Pull request workflow

1. Open or claim an issue. Anything bigger than a typo fix starts as an issue so the scope is written down before the branch is cut.
2. Branch from main. Use the naming convention above. Long-lived epic branches are the exception — they live until their PR merges.
3. Keep the diff focused. One concern per PR. If you find an unrelated bug, open a second PR.
4. Run the checks locally. cargo fmt, cargo clippy, cargo test, and bun run build in frontend/. CI runs the same, but catching them locally saves a round trip.
5. Fill the PR description. State what changed, why, and how you tested it. Link the issue with Closes #N.
6. Walk the QA checklist. For anything that touches the grid, wizard, or export flows, step through QA-CHECKLIST.md. Note which items you covered in the PR description.
7. Wait for review. Default to squash-merge. A PR needs CI green plus one review before it lands.

What a reviewer is looking for

• Read-only integrity. No new code path mutates the target database. No INSERT, UPDATE, DELETE, or DDL — ever.
• No SQL surfaced to users. Every new UI affordance uses spreadsheet vocabulary: sort, search, filter, show, hide, export.
• Identifier validation. Anything that interpolates a table or column name into SQL passes through the whitelist in Security. Values use sqlx bind parameters.
• Tests that fail without your change. Bug fixes add a reproducer; features add happy-path and one edge case.
• Design fidelity. Frontend changes respect the --sk-* token system and the .impeccable.md brief. No new hardcoded colours, no glass on interior surfaces.
• Commit hygiene. Atomic commits with Conventional Commit subjects. If you lost the thread mid-PR, git rebase -i before review.
• Docs in the same PR. If you changed the UI or the config, update the matching page under /get-started, /features, or /operate.