Skip to content

Commit 9da4c8d

Browse files
committed
docs(releases,upgrading): read the plan before the destructive apply, and drop --yes from it; preview skills before removing them
Claude-Session: https://claude.ai/code/session_01FM29ZqLTrnPNXxijioZwMp Co-authored-by: Claude <noreply@anthropic.com>
1 parent b6917f0 commit 9da4c8d

3 files changed

Lines changed: 39 additions & 10 deletions

File tree

‎content/docs/releases/v18/18-0.mdx‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,8 @@ not walked, and no upgrade of a production application was run for this page.
176176
npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
177177
```
178178

179+
`npx skills list` shows what is installed first — the walk listed the ten
180+
`objectstack-*` skills — and the removal deletes only the names it is given.
179181
Run before the removal, the sync skips every skill a `skills add` installed,
180182
exits `0`, and leaves the 17.x-era skill text in place:
181183

@@ -256,15 +258,29 @@ the lines below are the walk's measured output for each step.
256258
`org_owner` and `admin_full_access`; the three notes read back with their
257259
organization, and a fourth was written; an API key minted on 17.7.0 still
258260
answered `200`. *Measured in the walk.*
259-
- **Then clear the drift that remains.** The first served boot still logged
260-
three orphaned columns (`sys_comment.reactions`,
261-
`sys_sso_provider.created_by` / `updated_by`). Carry the stored emoji
261+
- **Then clear the drift the ceremony leaves, and only that.** The first served
262+
boot still logged three orphaned columns (`sys_comment.reactions`,
263+
`sys_sso_provider.created_by` / `updated_by`; on the `group` walk's database
264+
also the index `idx_sys_sso_provider_organization_id`). Carry the stored emoji
262265
reactions into `sys_comment_reaction` records first —
263266
`os migrate comment-reactions` to preview, then
264267
`os migrate comment-reactions --apply --yes`, which printed
265268
`✓ Converted 1 reaction(s); … the run is recorded as verified` (`9963322`,
266-
`6673c80`) — then `os migrate apply --allow-destructive --yes`, which dropped
267-
the three columns. The next boot logged no drift, and the reaction read back
269+
`6673c80`); without `--yes` it applies nothing and asks for it. Then run
270+
`os migrate plan` and read its destructive entries: ⛔ go on only if they are
271+
the ceremony's leftovers listed here. `os migrate apply --allow-destructive`
272+
applies **every** destructive change in the plan, drops and tightenings
273+
alike, so any other entry is your app's own — a column that may hold data —
274+
and is decided separately, not in this step. Then run
275+
`os migrate apply --allow-destructive` in a terminal: it prints the changes
276+
and asks `Apply 4 change(s) to DATABASE? [y/N]` (four on the `group` walk's copy); answer
277+
`y` only when the list is the one you checked (`n` printed
278+
`ℹ Aborted — no changes made.`). In a non-interactive shell it applies
279+
nothing, prints
280+
`⚠ Confirmation required. Re-run with --yes to apply, or use "os migrate plan" to preview.`
281+
and still exits `0`: read the output, not the exit code. The walk itself ran
282+
`os migrate apply --allow-destructive --yes` after that check, which dropped
283+
the three columns; the next boot logged no drift, and the reaction read back
268284
from `sys_comment_reaction`. *Measured in the walk.*
269285

270286
**A development database (`os dev`).** Measured on a 17.7.0 app whose database

‎content/docs/releases/v18/index.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,9 @@ every flag is in
111111
project, `npm install --save-dev` fails (`npm error Cannot read properties of
112112
null (reading 'edgesOut')`, measured on the [18.0.0 upgrade
113113
walk](/docs/releases/v18/18-0#1-move-the-pins)). `npx skills remove --all`
114-
replaces the first command when these are the only skills the project has.
114+
replaces the first command when these are the only skills the project has:
115+
run `npx skills list` first, because `--all` removes every installed skill
116+
without asking.
115117
- **18.0.0 ends the prerelease.** It is the GA cut: it leaves pre mode and
116118
publishes the line to `latest`.
117119

‎content/docs/upgrading.mdx‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,9 @@ command for this move; it is four steps you run yourself.
114114

115115
The list names every skill the catalog carried during 17.x, and a name that
116116
is not installed is skipped; `npx skills remove --all` does the same when
117-
these are the only skills the project has.
117+
these are the only skills the project has. Run `npx skills list` first:
118+
`--all` removes every installed skill without asking, so use it only when
119+
the list shows nothing but these.
118120

119121
Then run [the loop](#the-loop) below — `os validate` before `os build` — because
120122
moving the pins can move the gate.
@@ -364,9 +366,18 @@ command.
364366
6. Apply exactly that plan:
365367
`os migrate organization-ownership --apply --plan-file plan.json --backup-taken`.
366368
7. Start the server again.
367-
8. Clear the orphaned columns the first served boot still reports:
368-
`os migrate comment-reactions --apply --yes`, then
369-
`os migrate apply --allow-destructive --yes`.
369+
8. Clear the orphaned columns the first served boot still reports, and only
370+
those. Preview the reactions with `os migrate comment-reactions`, then carry
371+
them with `os migrate comment-reactions --apply --yes`. Then run
372+
`os migrate plan` and check that its destructive entries are only the
373+
columns the ceremony left behind (in the walk: `sys_comment.reactions`,
374+
`sys_sso_provider.created_by`, `sys_sso_provider.updated_by`). Any other
375+
destructive entry is your app's own and is decided separately, not in this
376+
step: `os migrate apply --allow-destructive` applies every destructive change
377+
in the plan. Then run `os migrate apply --allow-destructive` in a terminal and
378+
answer its `[y/N]` prompt after reading the changes it lists. In a
379+
non-interactive shell it applies nothing, prints
380+
`⚠ Confirmation required. Re-run with --yes to apply …` and still exits `0`.
370381

371382
Each step's measured output, from a walk of a 17.7.0 app to 18.0.0, is in
372383
[the 18.0.0 upgrade checklist, step 2](/docs/releases/v18/18-0#2-upgrade-the-database).

0 commit comments

Comments
 (0)