Plan SDK-owned migrations for all Sentry SDK upgrades

Open
  • Is something wrong?
#1,630 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
github, javascript, node.js, typescript
Domain
backend-api-design, cli, devtools

Research direction

Start by reading lib/init/wizard-runner.ts and the sentry-wizard workflow, then review the migration engine described in getsentry/cli#1499 and the related upgrade idea in #1483. The issue is a broad plan with open questions about the migration contract, artifact index, and execution across languages; it does not identify a bounded implementation task or a completion test.

Written by the indexing model from the issue text.

Description

Upgrading across an SDK major still means reading the migration guide and fixing renamed options, moved imports, and removed exports by hand. getsentry/cli#1499 (by @msonnb) prototyped sentry migrate with a JS v10 → v11 codemod. That PR is closing with the getsentry/cli archive, and its review set a different direction. This issue records that direction as the plan for SDK upgrades in general. #1483 tracks the user-facing sentry sdk upgrade idea.

Design direction (from BYK's review of cli#1499)

  • The CLI is the harness, not the place where migrations live. It provides the runtime: detection, dry-run, safety checks, task execution, and reporting. Migration logic for each SDK lives in that SDK's repo, so the SDK team owns it.
  • Migrations load at runtime, not inside the binary. The CLI can't ship every migration for every SDK all the time, so it fetches or imports the migration for the detected SDK and version when it needs it.
  • Use the same backend as sentry init. Upgrades should run through the server-driven workflow that sentry init uses (lib/init/wizard-runner.ts, sentry-wizard workflow), with local tools doing the file work. @betegon owns this direction.
  • Fall back to a generic path (suggested by @HazAT). When no dedicated migration exists, detect the SDK and version range, read the changelog or migration guide for that range, and list the breaking changes for an agent to act on.

Plan

  1. Detection. Find the installed SDK(s) and version(s) in the project, reusing sentry init's platform and project detection. Get the target version from the release registry.
  2. Migration contract. Define what an SDK-published migration looks like, based on the engine in cli#1499:
    • A list of small tasks with stable ids. Each task checks whether it applies and makes no change when it doesn't.
    • Deterministic edits are applied directly. Call sites that need a human decision get a TODO.
    • A failing task doesn't stop the run. --only / --skip select tasks by id.
    • Output includes a report of what's left with file:line per item, which can be handed to an agent.
  3. Distribution. SDK repos publish migrations as versioned artifacts, listed in the release registry or a similar central index. The CLI downloads and caches them on demand. Nothing is embedded at build time.
  4. Harness behavior in the CLI. Carry over the safety rules from cli#1499:
    • Require git and a clean tree (--allow-dirty to override).
    • Support --dry-run.
    • Rewrite manifests (for example package.json) without installing anything.
    • Make re-runs safe.
  5. Agent handoff. Leftover items from a migration and the output of the generic fallback go to the init backend or an agent through the same channel, so both paths produce one result format.
  6. Command surface. Combine with #1483 into one entry point (for example sentry sdk upgrade [--to <version>] [--dry-run]) instead of a separate migrate command.

Rollout

  • Phase 0: Agree on the migration contract, the distribution and index format, and how it connects to the init backend. Owners: SDK teams, @betegon.
  • Phase 1: Build the harness and the generic changelog/migration-guide fallback. This covers every SDK without a dedicated migration.
  • Phase 2: Move the JS v10 → v11 migration from cli#1499 into getsentry/sentry-javascript as the first SDK-owned migration, and run it through the harness.
  • Phase 3: Write a guide for SDK teams on adding migrations for their next majors.

Open questions

  • Where does the migration index live: the release registry, or a new endpoint?
  • How do migrations run outside JS? For example, a sandboxed JS runtime in the CLI that runs codemods for any language, or server-side execution through the init backend.
  • How should ambiguous edits that can't be made deterministically be split between local codemods and agent-assisted steps?

Related: #1483, #1468, getsentry/cli#1499

via BYK.

--

View Junior Session in Sentry

Dominant language
TypeScript
Stars
961
Forks
179
Avg merge
15h 33m
Merged PRs (30d)
476

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from getsentry/toolkit

All issues in getsentry/toolkit

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.