Say that pull requests shipped, and write the migration check out

916ad0be2576 · AtlantisPleb · · parent 1d3187e15a16

Say that pull requests shipped, and write the migration check out

Two documents had drifted away from the system they describe, in opposite
directions.

`priv/docs/welcome.md` listed pull requests under "What is not here yet".
They ship: `/:owner/:repo/pulls` and `/pulls/:number` render in the
browser, the API serves index, show, create, update, and the stack
operations beside them, and five documentation pages describe all of it.
That page's own rule is that "where a page in these docs describes
something, that thing exists and you can click it", and a reader who
believed the sentence would never click. What is actually missing is
narrower and is now stated as such: a pull request can be opened, browsed
with its diff, commented on, and merged, but nothing records an approval,
a requested change, or a comment anchored to a line. Webhooks are still
absent. The page also called the CLI npm-distributed; it is one native
binary, and the sentence now points at Coder and its installer.

`docs/operations/production-deploy-runbook.md` told an operator to verify
a data-bearing migration by evaluating `/tmp/check.exs` -- a file the
runbook never shows you how to write. A step you have to invent is a step
that goes unreviewed, which is the opposite of what a verification step
is for, and it also failed `ExitRehearsalRunbookTest`: that test parses
every `rpc` command under `docs/` and requires it to call a function that
exists, precisely so a runbook step cannot read as executable without
being it. `Code.eval_file/1` named no OpenAgents function, so the gate had
been red on `main` since 8f282e9.

The three checks the prose already asks for are now three commands: the
rows the backfill should have written, the column's nullability and
default, and the constraints on the table. Each was run against a real
database before being written down.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014wPUM1Fr44hwBGPP42iMxP
Co-Authored-By
Claude Opus 5 (1M context) <noreply@anthropic.com>

Deploy story

What this commit did to the running system — joined from the forge receipt chain, the part a commit page elsewhere cannot show.

pushed
by user · WAL seq 458 · 2026-08-26T17:44:25.145745Z

Changed files

  • modified docs/operations/production-deploy-runbook.md
  • modified priv/docs/welcome.md

Diff

2 files changed, +31 -13

docs/operations/production-deploy-runbook.md modified +17 -7

@@ -358,17 +358,27 @@ still serving the previous release and nothing has been disturbed.

358 358
Verify what the migration wrote, rather than reading its exit status. A
359 359
migration that reports success can still have written the wrong values, and a
360 360
data-bearing migration is the one place where that is expensive and silent.
361
Query the affected rows directly:
362
363
```sh
364
docker exec openagents /app/bin/openagents rpc 'Code.eval_file("/tmp/check.exs")'
365
```
361
Query the affected rows directly.
366 362
367 363
For a column added with a backfill, check three things: the row values the
368 364
backfill was supposed to write, the column's `is_nullable` and
369 365
`column_default` in `information_schema.columns`, and any constraint the
370
migration created. Capture the same counts before the migration runs so the
371
after-state has something to be compared against.
366
migration created.
367
368
```sh
369
docker exec openagents /app/bin/openagents rpc 'OpenAgents.Repo.query!("SELECT count(*) FROM <table> WHERE <column> IS NULL") |> IO.inspect()'
370
371
docker exec openagents /app/bin/openagents rpc 'OpenAgents.Repo.query!("SELECT is_nullable, column_default FROM information_schema.columns WHERE table_name = $1 AND column_name = $2", ["<table>", "<column>"]) |> IO.inspect()'
372
373
docker exec openagents /app/bin/openagents rpc 'OpenAgents.Repo.query!("SELECT c.conname, pg_get_constraintdef(c.oid) FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid WHERE t.relname = $1", ["<table>"]) |> IO.inspect()'
374
```
375
376
Write the query out rather than staging a script and evaluating it. A step that
377
tells you to run a file it never shows you is a step you have to invent, and
378
what you invent is what goes unreviewed.
379
380
Capture the same counts before the migration runs so the after-state has
381
something to be compared against.
372 382
373 383
## 7. Rolling replacement
374 384
priv/docs/welcome.md modified +14 -6

@@ -6,13 +6,18 @@ documentation covers the parts you can use today.

6 6
## What is here now
7 7
8 8
OpenAgents [hosts Git repositories](/docs/repositories) that you can create,
9
import from GitHub once, clone, push, pull, and browse. Use the browser or the
10
npm-distributed [OpenAgents CLI](/docs/openagents-cli).
9
import from GitHub once, clone, push, pull, and browse. Use the browser or
10
[Coder](/docs/install-cli), the command-line agent, which installs as a single
11
binary.
11 12
12 13
The issue tracker includes issues, labels, milestones, assignees, and projects,
13 14
each with a browser view and a GitHub-compatible REST endpoint. Code browsing
14 15
renders files and commits in repositories that you can access.
15 16
17
[Pull requests](/docs/pull-requests) propose one branch into another, and
18
[stacks](/docs/stacked-pull-requests) order several of them so each builds on
19
the one before it.
20
16 21
Three surfaces exist to show the system's own work rather than yours. The
17 22
[changelog](/changelog) lists every change with the receipt chain that took it
18 23
live. [Status](/status) reports fleet health. The

@@ -20,10 +25,13 @@ live. [Status](/status) reports fleet health. The

20 25
21 26
## What is not here yet
22 27
23
Pull requests, code review, and webhooks are not built. Where a page in these
24
docs describes something, that thing exists and you can click it — a
25
documentation site that mixes shipped features with planned ones leaves you
26
unable to tell which half you are reading.
28
Code review and webhooks are not built. A pull request can be opened, browsed
29
with its diff, commented on, and merged, but nothing records an approval, a
30
requested change, or a comment anchored to a line.
31
32
Where a page in these docs describes something, that thing exists and you can
33
click it — a documentation site that mixes shipped features with planned ones
34
leaves you unable to tell which half you are reading.
27 35
28 36
## Compatibility
29 37

This page updates live while a promote is in flight · changelog