# Contributing to rdbms-playground

Contributions are welcome — bug reports, ideas, and pull requests. The
project lives on Gitea at
<https://git.lazyeval.net/oli/rdbms-playground>; please file issues and
open pull requests there. It's approaching its first public release, so
the most useful contributions right now are bug reports and rough edges
you hit while learning.

## Getting set up

The toolchain is pinned with a Nix flake, so dev and CI share one Rust
version. With [Nix](https://nixos.org/download) (flakes enabled):

```sh
nix develop          # a shell with the pinned toolchain
```

Run everything through `nix develop -c …` so you match CI exactly.

## The checks your change must pass

CI runs these on every push and PR; run them locally first, and **check the
exit code** (a piped `… | tail` can hide a failure):

```sh
nix develop -c cargo fmt --check
nix develop -c cargo clippy --all-targets -- -D warnings
nix develop -c cargo test
```

All three must be green, with no skipped tests. New behaviour needs tests —
the suite runs in tiers from unit up to a PTY-driven end-to-end harness.

## Branches and pull requests

- **`main` is protected** and always green; it isn't pushed to directly.
  Every change lands through a pull request.
- **Branch off `main`**, one logical change per branch, named with a
  conventional prefix: `feat/…`, `fix/…`, `docs/…`, `chore/…`,
  `refactor/…`, `test/…`, `ci/…`.
- **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/)
  (`feat:`, `fix:`, `docs:` …) and reference the issue (`… (#123)` /
  `Closes #123`).
- **Open a PR against `main`.** The CI gate must pass before it can merge;
  PRs land as merge commits — history is append-only, so please don't
  force-push or rebase shared branches.
- Keep one PR to one concern; don't fold unrelated changes together.

## User-facing text

Two rules bind anything a user can see (errors, help, notes):

- **Don't name the database engine** — say "the database" / "the engine".
- **Don't say "DSL"** — say "simple mode" / "advanced mode".

## Significant changes get a decision record

Architectural or otherwise consequential changes are recorded as ADRs in
[`docs/adr/`](docs/adr/) — start with [`docs/adr/README.md`](docs/adr/README.md).
If your change touches a decided area, read the relevant ADR first; if it
would change a decision, propose a new ADR rather than quietly diverging.
Opening an issue to discuss a substantial change before building it is
always welcome.

## Code style

Match the surrounding code — its naming, comment density, and idioms. The
Clippy nursery lints are enabled and must pass clean.

## License of contributions

Unless you explicitly state otherwise, any contribution you intentionally
submit for inclusion in this project — as defined in the Apache-2.0
license — shall be **dual-licensed under `MIT OR Apache-2.0`** (the
project's licenses), without any additional terms or conditions.

This is the standard Rust "inbound = outbound" arrangement: your
contribution is offered under the same licenses the project distributes
under, so — via Apache-2.0 §5 — it carries the Apache-2.0 §3 patent grant
to all users. No separate CLA is required.