Docs / Integrations / Migration mode

Migration guide

A guide from the snapshot, then a narrow edit of the version strings. It does not rewrite your source code.

The guide

A dry run prints this before the diff.

• Where the dependency is, the version Stellar publishes, the protocol, and the observation time. If the snapshot has no protocol number, the guide says so.
• Numbered steps: the version string kedgeway will change, the commands you run, and a check that your Stellar CLI and the network you deploy to target that protocol. kedgeway reads neither.
• For soroban-client and unscoped stellar-sdk, the files and lines that import them, up to 20. The search uses the same depth and skipped directories as the manifest scan, and does not follow symlinks.
• Raven doc hits whose title or url is a migration document. A page that only mentions a migration inside a snippet is left out. If none qualify, the guide says no upgrade guide came back.

Run it

kedgeway migrate [path]            # dry run (default): prints a guide and a diff, edits nothing
kedgeway migrate [path] --dry-run  # the same; cannot be combined with --write
kedgeway migrate [path] --write    # applies the edits
kedgeway migrate . --fixture snapshot.json
kedgeway migrate . --offline       # cached snapshot only (also --no-cache, --max-age)

What it changes

• Rust. A deprecated or behind soroban-sdk is bumped to the exact current version (for example 28.0.0). Only the quoted version string on that one line changes, so comments, features and formatting stay. workspace = true members are left alone and the workspace root is bumped instead. =, ~ and ^ prefixes are kept; other ranges (>=, <) become manual steps.
• JavaScript. @stellar/stellar-sdk is bumped to the current version, keeping ^ or ~ (exact pins stay exact). package.json keeps its key order and indentation.
• Legacy packages. soroban-client and the unscoped stellar-sdk are replaced by @stellar/stellar-sdk at ^current, plus a manual step listing rg patterns for the imports you must update yourself.
• Aliases. A member such as "stellar-sdk": "npm:@stellar/stellar-sdk@^12.0.0" is read as the real package. A bump rewrites the value in place to npm:@stellar/stellar-sdk@^<current>, keeping the prefix. An alias of a legacy package is replaced wholesale by "@stellar/stellar-sdk": "^<current>". An alias with no version becomes a manual step.

What it refuses

• @stellar/stellar-base is a manual step, because the snapshot has no current base version.
• It never runs cargo or npm. It prints the follow-up commands instead: cargo update -p soroban-sdk and npm install.
• --write is refused if a file it would touch has uncommitted changes in git. The check passes silently only when git is not installed or the path is not in a repository. Any other git failure also refuses the write.
• Anything it cannot do safely is listed as a manual step with its reason. Only plain versions are edited: 12.x, 12 || 13 and comma ranges become manual steps, and dependencies in peerDependencies, optionalDependencies, overrides or resolutions are left alone. kedgeway never guesses.
• Edits are byte-exact: for package.json only the affected spans change, and writes are atomic. Symlinked manifests are never edited.

Lockfiles

• migrate decides from the resolved version when a lockfile exists, then edits the manifest only. It never edits a lockfile.
• When the manifest already allows the current major but the lockfile pins an older version, a bump would change nothing. kedgeway emits a manual step to refresh the lockfile instead: cargo update -p soroban-sdk, npm update <name>, pnpm update <name> or yarn upgrade <name>.
• Whenever a planned file has a lockfile, the plan also reminds you that the edits do not update it.

Exit codes