Update migration notes for sendDefaultPii in SDK

[adinauer]

Added migration details for sendDefaultPii behavior in data collection options, clarifying backfill conditions and implications for SDKs.

DESCRIBE YOUR PR

Tell us what you're changing and why. If your PR resolves an issue, please link it so it closes automatically.

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
• 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

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 GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Sep 10, 2026 3:02pm UTC
sentry-docs	Error		Sep 10, 2026 3:02pm UTC

[github-actions]

Please update the IS YOUR CHANGE URGENT? section of the PR description:

• Select exactly one option.
• If you selected an urgent or other deadline, provide the date as YYYY-MM-DD.

This information helps the Docs team prioritize your review.

[adinauer]

Put this as MUST NOT on purpose without mentioning that in theory it's possible to start backfilling in a major. Even with a major, we'd implicitly be forcing our customers to switch to data collection and re-evaluate what data the SDK sends. The way this is worded means customers can keep using sendDefaultPii without being bothered by data collection.

[s1gr1d]

The docs here are meant as directions for users so we have a shared agreement on how to document the changes. E.g. when someone set sendDefaultPii: true, users can omit dataCollection entirely as the new defaults have this behavior.

With the new sentence above ("if the SDK..."), those instructions now read as backfill rules for the SDKs (which they are not meant to be).

So far, we don't have explicit guidance in the spec on how to do the migration within the SDKs. But I agree that it's worth to add them. Or at least make this section clearer on what it actually communicates.

For example:

- Previous **`sendDefaultPii: true`** → users can omit `dataCollection` entirely; the new defaults already populate `user.*` and collect HTTP bodies. Add overrides only to restrict collection.
- Previous **`sendDefaultPii: false`** → users should opt out of the categories the new defaults collect.

And the first sentence could be grouped together with the rest of the instructions that are meant for SDKs. It makes a lot of sense to add docs for what an SDK must do when the old sendDefaultPii does not map 1:1 onto dataCollection.

[s1gr1d]

I think this is pretty hard to read as the sentences are very long.

Suggested change

	If the SDK can not cleanly map `sendDefaultPii` behavior to data collection options, it **MUST NOT** backfill data collection options from the configured `sendDefaultPii` value. Instead the SDK **MUST** ignore the value of `sendDefaultPii` if any data collection options is set explicitly and instead use the default data collection options where no explicit value has been set.
	This prevents breaking changes in PII filtering and allows customers to migrate to data collection at their own pace. Customers may keep using `sendDefaultPii` without changes to SDK behavior as long as they don't opt into data collection.
	If the SDK cannot cleanly map the `sendDefaultPii` behavior to data collection options, it **MUST NOT** derive data collection options from the configured `sendDefaultPii` value. Instead, the following rules apply:
	- if the user sets at least one data collection option, the SDK **MUST** ignore `sendDefaultPii`. The SDK **MUST** apply the options the user set, and the spec defaults for all other options. [This also means that the SDK might send more data when `sendDefaultPii` was `false` before, so users should be made aware of that.] <-- we should probably explicitly add this sentece
	- If the user sets no data collection options, the SDK **MUST** keep the legacy `sendDefaultPii` behavior unchanged.
	This prevents breaking changes in PII filtering and allows customers to migrate to data collection at their own pace. Customers may keep using `sendDefaultPii` without changes to SDK behavior as long as they don't opt into data collection.