chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)
ci / gate (push) Successful in 2m5s
ci / manifests (push) Successful in 4s
ci / gate (pull_request) Successful in 2m5s
ci / manifests (pull_request) Successful in 4s

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:
claude@clouddev1
2026-06-23 20:41:42 +00:00
parent e845a6ee72
commit b5c848efcb
10 changed files with 694 additions and 11 deletions
+61
View File
@@ -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