Repository navigation
Commit de6d835
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
- packages/testing/tests
- fixtures
- scripts
- tests
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
92 | 92 | | |
93 | 93 | | |
94 | 94 | | |
95 | | - | |
96 | | - | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
97 | 101 | | |
98 | | - | |
99 | | - | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
100 | 122 | | |
101 | 123 | | |
102 | 124 | | |
| |||
0 commit comments