chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)
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.
This commit is contained in:
@@ -7,6 +7,67 @@ 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
|
||||
|
||||
Reference in New Issue
Block a user