docs(sdk): key the version-file rule on the outgoing version's migration - #3669
Merged
Conversation
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
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
currentin 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
fulcrum2.1.1:13 → :14::13carries thedb_membackfill and had shipped two days earlier, so almost every install was still below it and would have skipped it.What changed
current.ts.The claim was stated in five places, all keyed on the incoming bump:
versions.mdworkflow.mdrecipe-version-migrations.mdagent-context.mdagent-context.mdis the one to note: it ships into every packaging workspace asAGENTS.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.mdentry.