Public: anyone can read this; the crew can change it.
docs/SPAWN.md says what tell-me and take-updates do now, with a test that keeps it honest #2663
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/2660-docs-spawn-md-says-what-tell-me-and-take → main 1 commit fork
2 files
changed +44
−5
docs/SPAWN.md +22 −5
| @@ -87,11 +87,8 @@ The spawner chooses `followMode` in the spawn input: `tell-me` (default) or | ||
| 87 | 87 | `take-updates`; it is part of the plan. `/:owner/forge/following` on the |
| 88 | 88 | child shows the chain, root first, one line per hop with its mode and how |
| 89 | 89 | many commits of its own it had when the next hop was born (the last hop is |
| 90 | counted now). Behind-counts are not shown: they need a fetch of the parent, | |
| 91 | which spawn does not do; that waits on cross-forge following (#1052), which | |
| 92 | is also what will make `mode` act. Until a follower acts on it, `tell-me` | |
| 93 | and `take-updates` are the owner's recorded choice, shown on the chain, not | |
| 94 | behaviour. | |
| 90 | counted now). What the modes do is in | |
| 91 | "Following the parent forge" below. | |
| 95 | 92 | |
| 96 | 93 | Every door reads and cuts the chain the same way: the page |
| 97 | 94 | (`GET /:owner/forge/following`), `GET /api/v1/repos/:owner/forge/following` |
| @@ -102,6 +99,26 @@ Sever's one implementation is `severForge` in `src/actions/follow.ts`. | ||
| 102 | 99 | A child's heartbeat adds `forgeTip` and `severedAt` when it carries a fork; |
| 103 | 100 | `/family` on the parent shows `code at <tip>` or `follows nothing since …`. |
| 104 | 101 | |
| 102 | ## Following the parent forge | |
| 103 | ||
| 104 | An hourly check (`CHECK_MS`, `src/spawn/upstream.ts`) fetches the parent's | |
| 105 | code into the child's `forge` repository under `refs/upstream/*`. What it | |
| 106 | learned (the parent's tip, how far behind the child is) is kept in | |
| 107 | `upstream.json` under the app's data directory. Fetching changes no branch. | |
| 108 | ||
| 109 | The owner's `followMode` decides what happens when the parent has new commits: | |
| 110 | ||
| 111 | - `tell-me` sends one inbox card per new tip, listing its commits. | |
| 112 | - `take-updates` opens one pull from the branch `forge/take-updates` | |
| 113 | (`TAKE_BRANCH`) holding the parent's code, and updates that same pull when | |
| 114 | the parent moves again. The pull carries the check like any other. | |
| 115 | ||
| 116 | The chain page, the API, the terminal and the MCP also offer "take now", | |
| 117 | which opens the same take pull. Sever stops all of it. | |
| 118 | ||
| 119 | What never happens: the default branch is never moved, and nothing merges | |
| 120 | itself. A person merges the take pull. | |
| 121 | ||
| 105 | 122 | **Sever** (`POST /:owner/forge/following/sever`, owner only, same-origin, |
| 106 | 123 | type `sever`) writes `severedAt` into `forgeCode` and nothing else: the |
| 107 | 124 | fork, its history and the record of where it came from stay, and nothing |
test/spawn-doc.test.ts added +22
| @@ -0,0 +1,22 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { readFileSync } from "node:fs"; | |
| 3 | import { join } from "node:path"; | |
| 4 | import { CHECK_MS } from "../src/spawn/upstream.ts"; | |
| 5 | import { TAKE_BRANCH } from "../src/spawn/take.ts"; | |
| 6 | import { FOLLOW_MODES } from "../src/spawn/chain.ts"; | |
| 7 | ||
| 8 | const doc = readFileSync(join(import.meta.dir, "..", "docs/SPAWN.md"), "utf8"); | |
| 9 | ||
| 10 | test("the doc has the section on following the parent forge", () => { | |
| 11 | expect(doc).toContain("## Following the parent forge"); | |
| 12 | expect(doc).not.toContain("not\nbehaviour"); | |
| 13 | }); | |
| 14 | ||
| 15 | test("the doc names the check interval, the take branch and both follow modes", () => { | |
| 16 | expect(CHECK_MS).toBeGreaterThan(0); | |
| 17 | expect(doc).toContain("`CHECK_MS`"); | |
| 18 | expect(doc).toContain(`\`${TAKE_BRANCH}\``); | |
| 19 | for (const m of FOLLOW_MODES) expect(doc).toContain(`\`${m}\``); | |
| 20 | expect(doc).toContain("refs/upstream/*"); | |
| 21 | expect(doc).toContain("upstream.json"); | |
| 22 | }); |
new above
offline