feat(python): Add the 3.x migration guide

[sentrivana]

We'll release an alpha version of the new major of the Python SDK soon. Preparing a migration guide to go with it.

Direct link to preview: https://sentry-docs-git-ivana-pythonmigration-guide-30.sentry.dev/platforms/python/migration/2.x-to-3.x

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: ~8 April
• 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

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 6, 2025 8:03am

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
changelog	⬜️ Ignored (Inspect)	Visit Preview		May 6, 2025 8:03am
develop-docs	⬜️ Ignored (Inspect)	Visit Preview		May 6, 2025 8:03am

[codecov]

Bundle Report

Changes will increase total bundle size by 168 bytes (0.0%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	11.14MB	174 bytes (0.0%) ⬆️
sentry-docs-client-array-push	9.47MB	-6 bytes (-0.0%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
1729.js	-3 bytes	1.75MB	-0.0%
../instrumentation.js	-3 bytes	1.08MB	-0.0%
9523.js	-3 bytes	1.05MB	-0.0%
../app/[[...path]]/page.js.nft.json	61 bytes	388.54kB	0.02%
../app/platform-redirect/page.js.nft.json	61 bytes	388.45kB	0.02%
../app/sitemap.xml/route.js.nft.json	61 bytes	386.42kB	0.02%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
static/chunks/pages/_app-*.js	-3 bytes	868.7kB	-0.0%
static/chunks/8165-*.js	-3 bytes	410.1kB	-0.0%
static/90BhbfJg33bumlvDLM31L/_buildManifest.js (New)	578 bytes	578 bytes	100.0% 🚀
static/90BhbfJg33bumlvDLM31L/_ssgManifest.js (New)	77 bytes	77 bytes	100.0% 🚀
static/jYozXpIJzN-*.js (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️
static/jYozXpIJzN-*.js (Deleted)	-578 bytes	0 bytes	-100.0% 🗑️

[getsantry]

This pull request has gone three weeks without activity. In another week, I will close it.

But! If you comment or otherwise update it, I will reset the clock, and if you add the label WIP, I will leave it alone unless WIP is removed ... forever!

---

"A weed is but an unloved flower." ― Ella Wheeler Wilcox 🥀

[sfanahata]

@sentrivana - I'm doing PR cleanups, and just checking in that you still want to keep this draft.

[sentrivana]

@sfanahata Yes, let's keep this open please -- unless it's cluttering up things for you, in that case feel free to close and I'll reopen once we have some content.

[sentrivana]

Thanks @sfanahata!

My biggest question is in how, when, or whether, this migration guide indicates a need to update our Python docs. There is quite a bit being deprecated and changed. What should we do with the existing docs referencing 2.x features?

The plan is to release an alpha version of SDK 3.0 soon (probably next week). We want to have the migration guide ready in the docs when the release is out so that folks who want to try out the alpha have nice human-readable instructions on how to upgrade.

After the alpha is out, we'll do some testing and dogfooding -- and work on a bigger docs update where we'll add 3.x-specific versions of existing pages (with set_attribute instead of set_data, etc.) that you can get to via the version picker. We want to support both folks on older SDKs and new for a while. So I wouldn't change existing pages, but rather add a set of separate pages on top. We'll take care of this in the coming weeks.

The goal is to have the docs fully up-to-date with the release of 3.0 stable (which is still some weeks away).

[sentrivana]

Added an additional tiny section: 98af38e

[sentrivana]

Also added an additional Alert to clarify that there is no stable 3.0 release yet: https://github.com/getsentry/sentry-docs/pull/11327/files#diff-b042f1a373d5c38a7136bf5c324bcea40a9a505402206f15e99521d6409abb46R7-R11

[antonpirker]

Some smaller wording suggestions and links. Up to you if you want to add them or not.

Otherwise: Great migration guide, shows how much we changed! :-)