Skip to content

feat(javascript): Add interactive JavaScript v11 migration guide - #19076

Merged
msonnb merged 17 commits into
masterfrom
ms/hackweek-js-v11-migration
Sep 11, 2026
Merged

msonnb merged 17 commits into
masterfrom
ms/hackweek-js-v11-migration

Conversation

@msonnb

@msonnb msonnb commented Aug 19, 2026 •

Copy link
Copy Markdown
Member

DESCRIBE YOUR PR

Adds an interactive v10-to-v11 migration guide for the JavaScript SDKs. Breaking changes live as tagged MDX items in includes/migration/javascript-v11/, and the guide filters them down to what applies to the reader's setup, either from a pasted package.json / Sentry.init() block or from checkboxes.

  • New page at /platforms/javascript/migration/v10-to-v11/interactive/, rendered into all 34 supported JavaScript guides
  • The root /migration/v10-to-v11/ page is currently a shell (intro, self-hosted compatibility, version support timeline) that links to the interactive guide. The one-page classical guide body still needs to be written and will follow.
  • scripts/validate-migration-items.mjs (wired into pnpm test) validates item frontmatter, since a mistyped facet would silently drop a change from someone's guide

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

  • Urgent deadline (GA date, etc.):
  • Other deadline:
  • None: Not urgent, can wait up to 1 week+

SLA

  • Teamwork makes the dream work, so please add a reviewer to your PRs.
  • Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
    Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

  • Checked Vercel preview for correctness, including links
  • PR was reviewed and approved by any necessary SMEs (subject matter experts)
  • PR was reviewed and approved by a member of the Sentry docs team

@vercel

vercel Bot commented Aug 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sentry-docs Ready Ready Preview Sep 11, 2026 8:43am UTC
1 Skipped Deployment
Project Deployment Actions Updated
develop-docs Ignored Ignored Preview Sep 11, 2026 8:43am UTC

Request Review

@msonnb msonnb changed the title feat(migration): Add interactive JavaScript v11 migration guide feat(javascript): Add interactive JavaScript v11 migration guide Aug 19, 2026
@msonnb
msonnb force-pushed the ms/hackweek-js-v11-migration branch from 3a0968d to 845d4be Compare September 1, 2026 09:04
@github-actions github-actions Bot added the Priority: Normal Docs review has no urgent deadline label Sep 1, 2026
andreiborza added a commit that referenced this pull request Sep 8, 2026
## DESCRIBE YOUR PR

Fills in the one-page v10 to v11 migration guide for the JavaScript
SDKs, which was a placeholder before. The content follows the SDK's
[`MIGRATION.md`](https://github.com/getsentry/sentry-javascript/blob/develop/MIGRATION.md).

- Long tables (span names, span ops, attribute renames) and optional
details are in expandable sections
- Framework and runtime specific changes are filtered per guide, so each
platform page only shows what applies to it

This is the bottom of a stack. #19076 (interactive guide) goes on top of
it and adds the link to the interactive version.

## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the
due date. You can update this information later by editing the PR
description.

- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] No deadline: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
supplied a deadline.

Thanks in advance for your help!

## PRE-MERGE CHECKLIST

_Make sure you've checked the following before merging your changes:_

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Francesco Gringl-Novy <francesco.novy@sentry.io>
Co-authored-by: Jan Peer Stöcklmair <jan.peer@sentry.io>
msonnb and others added 6 commits September 10, 2026 13:10
Adds an interactive guide for the Sentry JavaScript SDK v10-to-v11 upgrade,
rendered into every JavaScript platform and guide page via `<MigrationGuide />`.

- 88 breaking changes as standalone MDX items in
  `includes/migration/javascript-v11/`, each tagged with the phase, severity,
  frameworks, platform category and features it applies to
- A server component that drops items the current guide cannot use, and a
  client shell owning facet filtering, per-guide checklist state and the
  copy-for-agent prompt
- Setup detection that reads facets and the SDK package off a pasted
  `package.json` or `Sentry.init()` block, and links readers to the right guide
  when they are on the wrong one
- A frontmatter validator run by `pnpm test`, with `pnpm migration-items` for
  the breakdown by phase, severity and category
- Interactive chrome is excluded from the `.md` exports, so agents fetching a
  page get the guide without controls they cannot operate

Adds the missing `categories` frontmatter to the Effect guide, without which
the migration page showed browser-only items on a server-only SDK.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Comment thread src/components/migrationGuide/detect.ts Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 19bf4a0. Configure here.

Comment thread scripts/validate-migration-items.mjs Resolved
@msonnb

msonnb commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

@andreiborza I did one more pass over all items and made sure they all align in wording and structure with the static guide

@andreiborza andreiborza left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ship it crucial

Comment on lines +66 to +68
.filter(item => {
if (item.frameworks !== 'all' && !item.frameworks.includes(framework ?? '')) {
return false;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The migration guide page will crash with a TypeError because it does not handle cases where an item's frameworks frontmatter property is undefined.
Severity: CRITICAL

Suggested Fix

Add a runtime check in src/components/migrationGuide/index.tsx to ensure item.frameworks is an array before calling .includes() on it. Additionally, integrate the validation script (pnpm migration-items) into the CI pipeline (pnpm test) to prevent invalid migration items from being merged in the future. Finally, correct the 10 existing migration items that have an empty frameworks: value.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: src/components/migrationGuide/index.tsx#L66-L68

Potential issue: The migration guide component at
`src/components/migrationGuide/index.tsx` filters items by calling `.includes()` on the
`item.frameworks` property. However, if a migration item's frontmatter has an empty
`frameworks:` key, the YAML parser returns `undefined` for this value. This leads to a
`TypeError: Cannot read properties of undefined (reading 'includes')` when the component
renders. The analysis found 10 existing migration items with this malformed frontmatter.
The validator script that should catch this is not integrated into the CI test suite,
allowing these invalid items to be deployed, which will break the migration guide pages
for all users.

Also affects:

  • scripts/validate-migration-items.mjs:10~11

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there are not 10 malformed migration items, and since these pages are statically generated the worst that could happen is that a preview build fails

@msonnb
msonnb merged commit e7f7225 into master Sep 11, 2026
28 checks passed
@msonnb
msonnb deleted the ms/hackweek-js-v11-migration branch September 11, 2026 09:44
inventarSarah pushed a commit that referenced this pull request Sep 29, 2026
)

## DESCRIBE YOUR PR

Adds an interactive v10-to-v11 migration guide for the JavaScript SDKs.
Breaking changes live as tagged MDX items in
`includes/migration/javascript-v11/`, and the guide filters them down to
what applies to the reader's setup, either from a pasted `package.json`
/ `Sentry.init()` block or from checkboxes.

- New page at `/platforms/javascript/migration/v10-to-v11/interactive/`,
rendered into all 34 supported JavaScript guides
- The root `/migration/v10-to-v11/` page is currently a shell (intro,
self-hosted compatibility, version support timeline) that links to the
interactive guide. The one-page classical guide body still needs to be
written and will follow.
- `scripts/validate-migration-items.mjs` (wired into `pnpm test`)
validates item frontmatter, since a mistyped facet would silently drop a
change from someone's guide

## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
ric-oliv added a commit that referenced this pull request Oct 29, 2026
<!-- Keep the urgency section so automation can prioritize this PR. You
may delete other sections you don't need. -->

## DESCRIBE YOUR PR

This PR adds the migration guide for version 7 of the Sentry SDK for
.NET, ready for the public release candidate, `7.0.0-rc.2`. It follows
the pattern of the Flutter v10 guide from #19390:

- A full guide at `/platforms/dotnet/migration/v6-to-v7/`, built from
one include per change in `includes/migration/dotnet-v7/`.
- An interactive checklist at
`/platforms/dotnet/migration/v6-to-v7/interactive/` that renders the
same includes through `<MigrationGuide migration="dotnet-v7" />`.
- An agent prompt callout that points at the guide's `.md` URL.
- A "Migrating to 7.x" section at the top of the existing .NET migration
page, which links to both.

Both pages live under `common/`, so they render for every .NET guide,
such as ASP.NET Core, MAUI, WPF and Serilog. Xamarin uses a separate
SDK, so the new pages exclude it. I didn't move the 6.x, 4.x and 3.x
sections, so every existing URL and anchor keeps working and the PR
needs no redirects.

To register the collection, the PR adds `dotnet-v7` to the `MIGRATIONS`
map in the `MigrationGuide` component and to the validator's
`COLLECTIONS` map, with specs for both. These changes in
`src/components/migrationGuide/` and `scripts/` touch code that the
JavaScript and Flutter guides share, so they need an approval from the
docs team. For reference, msonnb approved the last change to the
component in #19729, and andreiborza approved the JavaScript interactive
guide that added it in #19076.

The checklist shows one step only on the MAUI guide. Every other step
applies to every .NET guide, because .NET apps combine integrations,
such as a Serilog sink in an ASP.NET Core app.

I checked the guide against `7.0.0-rc.2` from nuget.org and against the
`version7` branch at getsentry/sentry-dotnet@a56c63455. The guide
describes 7.0.0. Where rc.2 still behaves differently, the release
candidate note at the top says so.

### Why this goes live during the release candidate

I'd like to merge this as soon as it's approved, while 7.0 is still in
release candidate. 7.0.0 GA is planned for 2026-11-30. People who try
the release candidate need the guide now, and the agent prompt needs a
published `.md` URL to point at.

Two develop-docs rules pull in different directions here. [Managing
Linear
projects](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/managing-linear-projects/#visibility-for-major-releases)
says docs "MUST NOT go live before the SDK ships". The [breaking changes
playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes/#6-update-docs-and-changelog)
says to publish the migration guide "before or alongside the major
release". I read the first rule as protecting users from docs for code
they can't get. Version `7.0.0-rc.2` is public on nuget.org, and the
guide's first block says it's a release candidate and names that
version. Other SDKs made the same call:

- The Python 2.0 guide merged on 2024-02-28, while only the `2.0.0a1`
alpha was out. Its note at the top said so.
- The JavaScript v11 guide merged on 2026-09-08 with `11.0.0-beta.1`
out, and its interactive version followed on 2026-09-11.
- The Flutter v10 guide merged on 2026-10-05 with `10.0.0-rc.2` out,
four days before 10.0.0.

### The release candidate note

The guide opens with one `<Alert>`. It says there is no stable 7.0 yet,
names `7.0.0-rc.2`, and says the rest of the .NET docs describe 6.x
until 7.0.0 ships. It also covers what only the release candidate has:

- `Logging.AddSentry()` after `ClearProviders()` doesn't add Sentry's
logger providers back yet. That came with getsentry/sentry-dotnet#5776,
after rc.2.
- `DecompressionMethods` still includes Brotli, which
getsentry/sentry-dotnet#5816 takes out of the default after rc.2. The
note says how to leave it out until then.
- An ASP.NET Core app that sends `ILogger` entries through NLog crashes
with `Debug` on, tracked in getsentry/sentry-dotnet#5822. The guide's
verify step turns `Debug` on, so the note says to leave it off in those
apps.
- Its `net11.0` builds depend on the .NET 11 release candidate versions
of three `Microsoft.Extensions` packages.

The rest of the guide describes 7.0.0 as released. At GA, I'll delete
that one block from `includes/dotnet-v7-migration-overview.mdx`, and
nothing else needs to change.

### What this PR leaves to other PRs

This PR only adds the guide and what it needs. The reference pages are
in other PRs, and this one doesn't need any of them to merge first:

- Logs and the logging integrations: #19925
- `Microsoft.Extensions.Logging` and ASP.NET Core: #19961
- OpenTelemetry propagation: #19924
- Release and environment: #19960
- Hangfire monitor schedules: #19781

Three links in the guide point to the "Apps That Call UseSentry"
sections that #19925 adds to the Serilog, NLog and log4net guides. Until
#19925 merges, they open those guides at the top, and the migration
guide sums up the same setups itself.

There is no page for the new `Sentry.Extensions.Hosting` package yet.
I'll link it from the guide once that page exists.

Refs https://linear.app/getsentry/issue/NET-860
Refs getsentry/sentry-dotnet#5710

## IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the
due date. You can update this information later by editing the PR
description.

- [x] Urgent deadline (GA date, etc.): 2026-11-30
- [ ] Other deadline: YYYY-MM-DD
- [ ] No deadline: Not urgent, can wait up to 1 week+

## PRE-MERGE CHECKLIST

_Make sure you've checked the following before merging your changes:_

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com>
Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>

This branch was successfully deployed

2 active (1 outdated) deployments
Preview – sentry-docs — 683104d7 Deployed Sep 11, 2026 by vercel[bot]
Preview – develop-docs — 0284564f Deployed Sep 11, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Priority: Normal Docs review has no urgent deadline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants