[turnipdabeets]

💡 Motivation and Context

Addresses ioannisj's review on #873 (#873): the 4.0 upgrade notes were spread across the changeset and several follow-up PRs. This adds a root MIGRATION.md for app developers upgrading from 3.x, which SPM checkouts also ship to coding agents. As suggested, the changes the compiler won't flag come before the compile errors.

Sections:

1. Before you upgrade: Xcode 26, deployment targets, moving from CocoaPods to SwiftPM, and a note that React Native and Flutter apps upgrade their wrapper instead.
2. Changes the compiler won't flag: replay always records masked screenshots (and what to mask), replay screen names, malformed and bootstrapped flag payloads, lifecycle version/build, 2.x queue files, reachability, and a short capture v1 checklist.
3. Compile errors and how to fix them: old → new tables (Swift and Objective-C where they differ), with snippets for propertiesSanitizer → setBeforeSend, didReceiveFeatureFlags → onFeatureFlags(_:), and @Sendable callbacks.
4. Package traits: turning off SessionReplay, CrashReporting and Surveys, and which public API goes away with each.

Also: a one-line pointer in README.md, and a link to the guide in the changeset's intro line (no new changeset file). The changeset link points at main, so it 404s until 4.0 merges to main.

Sections that depend on open PRs

The guide is written as if all of these land in 4.0. If one doesn't, adjust the listed part:

PR	Parts of MIGRATION.md
#972 (SPM only)	Requirements "Installation" row, "Move from CocoaPods to Swift Package Manager", "React Native and Flutter apps"
#973 (screenshotMode removed)	screenshotMode row in the Session replay compile-error table. Without it, the property is a deprecated no-op instead.
#974 (plain closure arrays in setBeforeSend)	Last sentence of "Callbacks are @Sendable". Without it, users must retype arrays as [BeforeSendBlock].
#975 (trait-off removes public API)	The "When a trait is off" table and the .postHogMask() note in "Package traits"
#976 (replay masking gaps)	The "Masking also covers more than in 3.x" paragraph (the secure-field sentence is already on the base branch)
#977 (fix-its, reachability)	"Xcode names the replacement, and offers a fix-it" in the compile-errors intro. The reachability bullets come from the base changeset and still hold.
#965 (didReceiveFeatureFlags removed)	didReceiveFeatureFlags row and snippet under Feature flags
#938 (capture v1)	"Capture v1" section, and the maxRetries → pushNotificationSubscriptionMaxRetries row

#938 and docs/migration-3.x-to-4.0.md: #938 adds its own detailed guide at docs/migration-3.x-to-4.0.md, and its changeset links there. This PR only summarizes what users must check. Whichever of the two merges second should move #938's detailed content into MIGRATION.md (or link to it from the "Capture v1" section) and repoint #938's changeset link at MIGRATION.md, so there's one guide.

💚 How did you test it?

Markdown only, so no SDK validation (per CLAUDE.md).

• git diff --check: clean.
• Every in-page anchor in MIGRATION.md matches a heading; CHANGELOG.md and MIGRATION.md relative links resolve.
• Checked the identifiers against the code: the base branch public API snapshot for current names, main's snapshot for removed 3.x names and Objective-C selectors (apiKey:, getFeatureFlagPayload:, PostHogLogLevelInfo, PostHogDataModeCellular), and the open PRs' diffs and descriptions for what they add or remove. BoxedBeforeSendBlock's Objective-C initializer is block: (from @objc(block:)), not initWithBlock:.
• Behavior claims come from the 4.0 changeset, the follow-up PRs, and the commits behind them (for example, the replay screen name change only affects the replay screen name, not $screen events).
• Not verified: choosing traits from an Xcode app project (needs Xcode 26.4+ per feat: add SessionReplay and CrashReporting package traits #916, which also notes a report of default traits staying on there), so the guide tells users to check their build. The wrapper SDK version numbers that adopt 4.0 aren't known yet, so the guide doesn't name them.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

No new changeset: the existing .changeset/v4-major-release.md intro now links to the guide.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Claude Code (Opus 5.5), directed by Anna Garcia. Read the 4.0 changeset, the open follow-up PRs (feat!: send events through capture v1 and add captureAi #938, chore!: remove the didReceiveFeatureFlags notification #965, chore!: publish 4.0 to Swift Package Manager only #972–chore: 4.0 fix-it stubs for removed APIs and review nits #977) and their diffs, and the base-branch code and API snapshots to check each name and behavior.
• Kept PR numbers and internal rationale out of the guide body; it's written for app developers. The capture v1 section is a checklist rather than a copy of feat!: send events through capture v1 and add captureAi #938's guide, to avoid two diverging documents.

🤖 Generated with Claude Code

[posthog]

PostHog Review · Standard · reviewed f2b1ef9: 1 Should fix.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[dustinbyrne]

The consolidated guide covers the v4 migration clearly. I have four non-blocking documentation clarifications below. Keep the conditional sections aligned with the final integrated 4.0 release.

AI-assisted review.