Skip to content

Commit de6d835

Browse files
authored
πŸ“ Make the README the development guide, and run it (#436)
* πŸ“ Make the README's development instructions runnable The README told a contributor what to run and could not run it. Its Development section is now a hierarchy of document targets β€” Setup, Build, and Verification with Focused and Complete beneath it β€” that composes the existing low-level tasks rather than reimplementing any of them. Preparation is the ancestor's: `deno task setup` lives in Development's direct content, so selecting Setup prepares a checkout and nothing else, and selecting any other leaf inherits it once. Ordinary target projection decides the rest; no conditionals and no target-sensitive code. A failed task has to stop the document, and one self-closing `<Output />` in the root preamble is what makes it: a root that declares an output region executes the rest as documentation, so the first nonzero exit aborts the run and later blocks and sibling sections never start. `deno task verify:focused` is the one task added, and it enters the README rather than the README entering it. * πŸ“ Let the README's commands be watched rather than swallowed The runnable Development section was written against contracts that had not landed. It declared a root `<Output />` because that was the only way a text root could fail, ran every task `silent` because a rendered transcript was the alternative to nothing, and redirected the changed-test report to /dev/null because a journaled report of this repository's own scanner fixtures is refused. All three are merged now. #453 settles an uncaught failure at any text root, so fail-fast needs no region. #441 forwards a command's output as it is produced and displays each byte once, so an ordinary `exec` block shows a build or a test run the way typing the command does. #442 keeps nothing without `--journal`, so there is no retained report for the gate to scan and no reason to discard one. So the section says what it now does: the commands stream, the exit status still decides, and `timeout=30m` still bounds the complete battery. The regression that pinned "a successful target renders nothing" is replaced by the one worth having β€” each command's output reaches the reader exactly once, in order β€” and RM12 now proves a credential-shaped report reaches the reader unscanned rather than proving a redirection hid it. * πŸ“ Make the README the repository's development guide It was a product page with a development section at the bottom: install instructions, a runtime tutorial, a document-model tour, roadmap and status. A contributor reading it to find out how to prepare a checkout read past most of it, and the repository already documents the product elsewhere. So the whole document is now the developer path, and the path is what it addresses. `Setup`, `Build`, `Test`, `Test/Focused` and `Test/Complete` are the five targets, the shared setup block sits in the preamble so every selection inherits it, and there is no `Development` prefix left to type. Each section says why you run it, how to invoke it, what it executes, and what a successful run provides β€” a prepared checkout, `dist/xmd`, feedback evidence, delivery verification. The detailed process moves to where it is owned: AGENTS.md for contribution and verification rules, architecture.md for the invariants, the executable spec for product behavior, and the dependency-layout facts a developer needs fold into Setup beside the command that establishes them. RM1 now asserts the catalog exactly, so a section that drifts back into product documentation β€” or a prose heading that would silently inherit the preamble's setup β€” shows up as an extra line. RM11 and RM12 are gone with the contracts they pinned: `xmd test`'s incidental execution and the credential canary were both about a README that no longer exists. * πŸ‘· Build the smoke job's binary through the README The README says how a contributor prepares a checkout and builds `xmd`. Until now CI said it separately, in its own two steps, which is the arrangement where documentation and tooling drift apart without either one noticing. The smoke job now runs `deno task xmd run README.md#Build` instead. It is the same work in the same order β€” preparation, then the compile β€” performed by the document that documents it, so a Build target that stopped working stops a required check. Everything after it is unchanged and consumes the `dist/xmd` that target produced. Preparation owns both dependency layouts, so the job gains the Node and pnpm setup the other jobs already have. No new job: the existing smoke job carries this, so `green.needs` is unchanged, and the focused and complete batteries stay where they are β€” the jobs that already run them in parallel. * πŸ”§ Prepare the checkout before the first source-CLI invocation The README opened with `deno task xmd targets README.md`, presented as the first command on a fresh clone. It is not one. Under the root `nodeModulesDir: "auto"` that task initializes `node_modules` itself, before any block in the document executes β€” a clean clone confirms it, going from no `node_modules` to 47 entries. So the guide was crediting its own Setup with work the bootstrap had already done, and a contributor following it would never see preparation as a step they took. `deno task setup` is now the first fresh-clone command, ahead of every `deno task xmd` example, and the source-CLI targets are introduced as what you run once the checkout is prepared. The executable block stays in the preamble, so every target still inherits preparation and RM2–RM7 are unchanged. The smoke job prepares the same way and for the same reason, then runs the Build target. The target prepares again β€” preparation is its preamble β€” and the repeat is deliberate: what the document does is not conditional on who ran it. A workflow regression pins the order against the *first* source-CLI invocation, so an `xmd` step added above the build reintroduces the defect and reds. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent d75ee90 commit de6d835

8 files changed

Lines changed: 465 additions & 332 deletions

File tree

β€Ž.github/workflows/ci.ymlβ€Ž

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -92,11 +92,33 @@ jobs:
9292
with:
9393
deno-version: v2.9.5
9494

95-
- name: Install dependencies
96-
run: deno task deps
95+
# `README.md#Build` prepares the checkout before it compiles, and
96+
# preparation owns both dependency layouts β€” so this job needs the Node
97+
# and pnpm halves as well as Deno's.
98+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
99+
with:
100+
node-version: "22"
97101

98-
- name: Build the xmd binary
99-
run: deno task build
102+
- uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
103+
104+
# Preparing the checkout is the installation owner's job, not a side
105+
# effect of the first `deno task xmd` to run: under
106+
# `nodeModulesDir: "auto"` that task would initialize `node_modules`
107+
# itself, before any README block executed. So this job prepares first,
108+
# exactly as the README tells a contributor to on a fresh clone.
109+
#
110+
# The Build target then prepares again, because preparation is its
111+
# preamble and every target inherits it. The repeat is deliberate: what
112+
# the document does is not conditional on who ran it.
113+
- name: Prepare the checkout
114+
run: deno task setup
115+
116+
# The README documents how a contributor prepares a checkout and builds
117+
# the binary, and this is that document doing it. Everything below
118+
# consumes the `dist/xmd` it produced, so a README whose Build target
119+
# stopped working stops this job.
120+
- name: Prepare and build through the README
121+
run: deno task xmd run README.md#Build
100122

101123
- name: Smoke test the compiled binary
102124
run: |

0 commit comments

Comments
Β (0)