claude@clouddev1
b5c848efcb
Adopt a trackable working method now the repo is public: - PRs onto a protected main; --no-ff merge commits; one worktree per branch. - Reserve-first ADR numbering: scripts/adr-reserve.sh claims the next number atomically against main (push = compare-and-swap; ledger docs/adr/RESERVATIONS.log), so a number is stable from creation. - Worktree helpers scripts/wt-new.sh + wt-clean.sh. - Local-origin test harnesses (reserve 10/10, worktrees 7/7, shellcheck clean). Record the decision in ADR-0059, supersede ADR-0000's placeholder-until-merge numbering default, and add the lean CONTRIBUTING.md sections + CLAUDE.md operational rules.
3.2 KiB
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 (flakes enabled):
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):
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
mainis 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
(
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/ — start with 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.