Skip to content

docs(sdk): key the version-file rule on the outgoing version's migration - #3669

Merged
dr-bonez merged 1 commit into
masterfrom
docs/sdk-version-file-migration-rule
Aug 11, 2026
Merged

docs(sdk): key the version-file rule on the outgoing version's migration#3669
dr-bonez merged 1 commit into
masterfrom
docs/sdk-version-file-migration-rule

Conversation

@MattDHill

Copy link
Copy Markdown
Member

The packaging guide asked "does this bump need a migration?" — a question about the version arriving in current.ts. The rule actually turns on the version leaving it, and the two disagree in exactly the case that matters: bumping over a version that carries a migration.

Taken literally, "no migration needed, so bump in place" deletes the outgoing version's migration from the graph. Every user still below that version then reaches the new current in one hop via the synthesized range vertex — so the update succeeds normally, having silently skipped the data migration. No error, nothing in the logs; the omission only surfaces later as unmigrated data.

This is not hypothetical. It nearly landed bumping fulcrum 2.1.1:13 → :14: :13 carries the db_mem backfill and had shipped two days earlier, so almost every install was still below it and would have skipped it.

What changed

  • States the principle the rule follows from — a migration belongs to the version that introduced it, permanently, and is never carried forward into a successor.
  • Re-keys the deciding question on the outgoing version, and makes explicit that the incoming version's needs only decide what goes into the new current.ts.
  • Adds a warning spelling out the silent-skip failure mode.
  • Closes the escape hatch in Why Released Versions Don't Need to Be Declared: "its own migration that must run in sequence on the way up" invited folding a migration into its successor on the grounds that ordering didn't matter. Correctness must not rest on a migration body being safe to apply twice, idempotent or not.

The claim was stated in five places, all keyed on the incoming bump:

File Where
versions.md the rule itself, the declared-node criterion, the Upstream Update and Wrapper-Only checklists
workflow.md Don't create unnecessary version files
recipe-version-migrations.md Solution
agent-context.md Working discipline

agent-context.md is the one to note: it ships into every packaging workspace as AGENTS.md, so packagers and agents were reading the wrong test as always-on context on every task.

Docs only — no SDK surface change, so no CHANGELOG.md entry.

The guide asked "does this bump need a migration?" — a question about the
version arriving in current.ts. The rule actually turns on the version
leaving it, and the two disagree in the case that matters: bumping over a
version that carries a migration.

Taken literally, "no migration needed, so bump in place" deletes the
outgoing version's migration from the graph. Every user still below that
version then reaches the new current in one hop via the synthesized range
vertex, so the update succeeds and silently skips the data migration --
no error, nothing in the logs, and the omission only surfaces later as
unmigrated data. Nearly hit exactly this bumping fulcrum 2.1.1:13 -> :14,
where :13 carries the db_mem backfill and had shipped two days earlier, so
almost every install was below it.

States the principle the rule follows from -- a migration belongs to the
version that introduced it, permanently, and is never carried forward --
and closes the escape hatch that "must run in sequence on the way up"
opened in the Why Released Versions section: folding a migration into its
successor is not licensed by the body happening to be idempotent, because
correctness must not depend on it being safe to apply twice.

Same claim was stated in five places, all keyed on the incoming bump:
versions.md (the rule, the declared-node criterion, the Upstream Update
and Wrapper-Only checklists), workflow.md, recipe-version-migrations.md,
and agent-context.md -- which ships into every packaging workspace as
AGENTS.md, so packagers were reading the wrong test on every task.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@dr-bonez
dr-bonez merged commit 3adc31a into master Aug 11, 2026
6 checks passed
@dr-bonez
dr-bonez deleted the docs/sdk-version-file-migration-rule branch August 11, 2026 21:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants