Plan SDK-owned migrations for all Sentry SDK upgrades

Ouverte
  • Quelque chose ne va pas ?
#1,630 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Fonctionnalité
Clarté
À clarifier
Activité
Active
Stack technique
github, javascript, node.js, typescript
Domaine
backend-api-design, cli, devtools

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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

Langage dominant
TypeScript
Étoiles
949
Forks
171
Merge moyen
1 j 3 h
PR mergées (30 j)
260

Préparer son environnement

Ce projet ne fournit ni conteneur de développement, ni Dockerfile, ni guide de contribution : l'installation est à votre charge. Commencez par son README, et consultez notre guide de la première contribution pour les étapes générales.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de getsentry/toolkit

Toutes les issues de getsentry/toolkit

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.