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.
82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# 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.
|