From 3a878692147db732cb51cb974d93e5d0b4f7703e Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Tue, 14 Jul 2026 15:19:35 +0200 Subject: [PATCH 1/5] docs: add CONTRIBUTING.md, issue and PR templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Covers setup, the day-to-day commands, and how to run each sandbox — the parts a new contributor needs that AGENTS.md (written for the SPEC->TEST-> IMPLEMENT->RECONCILE workflow) doesn't cover. The bug report template asks for an SSCCE so reports arrive reproducible instead of descriptive. --- .github/ISSUE_TEMPLATE/bug_report.md | 29 +++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/PULL_REQUEST_TEMPLATE.md | 9 ++++ CONTRIBUTING.md | 74 ++++++++++++++++++++++++++++ 4 files changed, 117 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..8b6dde4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,29 @@ +--- +name: Bug report +about: Something doesn't behave the way the engine promises +labels: bug +--- + +## SSCCE + +A **Short, Self-Contained, Correct (Compilable) Example** — the smallest +`setup()`/`machine()` config that still reproduces the bug, with nothing to +install or assume. Paste it as a single block; we should be able to copy it, +run it, and see the bug with zero edits. + +```ts +// paste your minimal repro here +``` + +## Expected + +What you expected the machine to do. + +## Actual + +What it actually did. + +## Version + +- `@dunky.dev/*` version: +- Runtime (Node / Bun / browser) + version: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1e306e4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Question or discussion + url: https://github.com/dunky-dev/state-machine/discussions + about: Not a bug? Start a discussion instead. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..32a55a0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,9 @@ +## What & why + + + +## Checklist + +- [ ] Tests pass (`pnpm test`), lint is clean (`pnpm lint`), types check (`pnpm typecheck`) +- [ ] Verified across every [scope](../AGENTS.md#scopes) the change touches +- [ ] Changeset added (`pnpm changeset`) if this is a user-visible change to a public package diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..be9437f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,74 @@ +# Contributing + +Thanks for looking into Dunky. This is the fast path to a working setup, the +commands you'll actually run, and how to file something useful. + +For the contribution _workflow_ (SPEC -> TEST -> IMPLEMENT -> RECONCILE), code +conventions, and boundaries, see [`AGENTS.md`](./AGENTS.md) — it's the same +contract agents follow here, and it applies to you too. + +## Setup + +```bash +git clone git@github.com:dunky-dev/state-machine.git +cd state-machine +nvm use # Node 24, pinned in .nvmrc +corepack enable # pnpm 11.10.0, pinned in package.json#packageManager +pnpm install +``` + +## Commands + +| Command | What it does | +| ------------------------------ | ---------------------------------------------------------- | +| `pnpm test` | Full test suite, watch mode | +| `pnpm test:ci` | Full test suite, once | +| `pnpm typecheck` | `tsc -b` across the whole workspace | +| `pnpm lint` | `oxlint` | +| `pnpm format` / `format:check` | `oxfmt` | +| `pnpm build` | Build every publishable package | +| `pnpm changeset` | Add a changeset — see [Versioning](./AGENTS.md#versioning) | + +Target one package or one file instead of the whole workspace: + +```bash +pnpm --filter @dunky.dev/state-machine test # one package's tests +pnpm vitest packages/core/tests/machine.test.ts # one test file +pnpm --filter @dunky.dev/react-state-machine build +``` + +## Run the sandboxes + +Each sandbox renders the same command-palette machine on a different +substrate — the fastest way to see a change actually work end to end. See +[`sandbox/README.md`](./sandbox/README.md) for what each one demonstrates; +the short version: + +```bash +pnpm -C sandbox/react dev # DOM — http://localhost:5173 +pnpm -C sandbox/opentui dev # terminal — needs Bun +pnpm -C sandbox/native start # Expo — needs a simulator or device +``` + +## Filing an issue + +A bug report is only as useful as its reproduction. Use an **SSCCE** — Short, +Self-Contained, Correct (Compilable) Example: + +- **Short** — the smallest machine config that still reproduces it. Strip + every state, guard, and action that isn't load-bearing. +- **Self-contained** — no missing imports, no "assume you have X set up." + Someone should be able to paste it and run it with nothing else. +- **Correct (compilable)** — it actually runs and actually reproduces the + bug. Not what you _think_ is happening — what you pasted and ran. + +The [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) asks for +exactly this. If you can't shrink your repro to an SSCCE, that's often a sign +the bug isn't where you think it is — shrinking it is frequently how you find +the real cause yourself. + +## Pull requests + +Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md) — it mirrors +`AGENTS.md`'s RECONCILE step: tests pass, lint and typecheck are clean, and a +changeset is included if the change is user-visible. From e39ebacb1d12b09805f2b0708635418a04d6fdc1 Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Tue, 14 Jul 2026 15:25:38 +0200 Subject: [PATCH 2/5] docs: restructure PR template around Why/What, Changes, Issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simpler than the checklist form — three short sections instead of a tickbox list. --- .github/PULL_REQUEST_TEMPLATE.md | 14 ++++++++------ CONTRIBUTING.md | 7 ++++--- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 32a55a0..7c14a13 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,11 @@ -## What & why +# Why/What - + -## Checklist +# Changes -- [ ] Tests pass (`pnpm test`), lint is clean (`pnpm lint`), types check (`pnpm typecheck`) -- [ ] Verified across every [scope](../AGENTS.md#scopes) the change touches -- [ ] Changeset added (`pnpm changeset`) if this is a user-visible change to a public package + + +# Issues + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be9437f..92e425a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -69,6 +69,7 @@ the real cause yourself. ## Pull requests -Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md) — it mirrors -`AGENTS.md`'s RECONCILE step: tests pass, lint and typecheck are clean, and a -changeset is included if the change is user-visible. +Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md): why and what the +change is, what changed, and any related issues. Before opening it, make sure +tests, lint, and typecheck pass, and a changeset is included if the change is +user-visible — that's `AGENTS.md`'s RECONCILE step. From 1e4d26e2a9a66d576c40d2ebd904c32da9e373b9 Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Tue, 14 Jul 2026 15:31:17 +0200 Subject: [PATCH 3/5] docs: ask PR authors to actually read their AI-assisted diffs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Not a ban on using AI — a request to reason about what it wrote before asking a reviewer to. --- CONTRIBUTING.md | 35 +++++++++++++++-------------------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92e425a..fe5a188 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,6 @@ # Contributing -Thanks for looking into Dunky. This is the fast path to a working setup, the -commands you'll actually run, and how to file something useful. - -For the contribution _workflow_ (SPEC -> TEST -> IMPLEMENT -> RECONCILE), code -conventions, and boundaries, see [`AGENTS.md`](./AGENTS.md) — it's the same +For the contribution _workflow_, code conventions, and boundaries, see [`AGENTS.md`](./AGENTS.md) — it's the same contract agents follow here, and it applies to you too. ## Setup @@ -12,8 +8,8 @@ contract agents follow here, and it applies to you too. ```bash git clone git@github.com:dunky-dev/state-machine.git cd state-machine -nvm use # Node 24, pinned in .nvmrc -corepack enable # pnpm 11.10.0, pinned in package.json#packageManager +nvm use +corepack enable pnpm install ``` @@ -31,13 +27,7 @@ pnpm install Target one package or one file instead of the whole workspace: -```bash -pnpm --filter @dunky.dev/state-machine test # one package's tests -pnpm vitest packages/core/tests/machine.test.ts # one test file -pnpm --filter @dunky.dev/react-state-machine build -``` - -## Run the sandboxes +## Sandbox Each sandbox renders the same command-palette machine on a different substrate — the fastest way to see a change actually work end to end. See @@ -45,9 +35,9 @@ substrate — the fastest way to see a change actually work end to end. See the short version: ```bash -pnpm -C sandbox/react dev # DOM — http://localhost:5173 -pnpm -C sandbox/opentui dev # terminal — needs Bun -pnpm -C sandbox/native start # Expo — needs a simulator or device +pnpm -C sandbox/react dev +pnpm -C sandbox/opentui dev # terminal — needs Bun +pnpm -C sandbox/native dev # Expo — needs a simulator or device ``` ## Filing an issue @@ -69,7 +59,12 @@ the real cause yourself. ## Pull requests -Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md): why and what the -change is, what changed, and any related issues. Before opening it, make sure -tests, lint, and typecheck pass, and a changeset is included if the change is +Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md). Before opening it, +make sure tests, lint, and typecheck pass, and a changeset is included if the change is user-visible — that's `AGENTS.md`'s RECONCILE step. + +If you used AI to help write this, read the diff like you wrote it yourself +before asking someone else to. Cut comments that don't say anything, drop +anything that drifted from what you're actually fixing, and be able to +explain any line if asked. A reviewer's time isn't the place to find out you +didn't. From 0041301cd69e832f3c04efe5d9c2d6f6447d4bf9 Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Tue, 14 Jul 2026 15:35:55 +0200 Subject: [PATCH 4/5] docs: split Pull requests into Humans and AI sections --- CONTRIBUTING.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe5a188..eeb6a21 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,12 +59,14 @@ the real cause yourself. ## Pull requests -Fill in the [PR template](.github/PULL_REQUEST_TEMPLATE.md). Before opening it, -make sure tests, lint, and typecheck pass, and a changeset is included if the change is -user-visible — that's `AGENTS.md`'s RECONCILE step. +### Humans -If you used AI to help write this, read the diff like you wrote it yourself +When using AI to help write changes, read the diff like you wrote it yourself before asking someone else to. Cut comments that don't say anything, drop anything that drifted from what you're actually fixing, and be able to -explain any line if asked. A reviewer's time isn't the place to find out you -didn't. +explain any line if asked. A reviewer's time isn't free. + +### AI + +Before opening it, make sure tests, lint, and typecheck pass, and a changeset is +included — see `AGENTS.md`'s RECONCILE step. From e935099cd9c9cfd4603f54764df84146a6a7750e Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Tue, 14 Jul 2026 15:37:32 +0200 Subject: [PATCH 5/5] Adjust wording --- .github/ISSUE_TEMPLATE/bug_report.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 8b6dde4..cfcede7 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -17,7 +17,7 @@ run it, and see the bug with zero edits. ## Expected -What you expected the machine to do. +What you expected it to do. ## Actual @@ -26,4 +26,3 @@ What it actually did. ## Version - `@dunky.dev/*` version: -- Runtime (Node / Bun / browser) + version: