docs: add 2.x to 3.x migration guide

[jamesnrokt]

Summary

MIGRATING.md had no 2.x → 3.x guide — its sections were written as incremental
notes within the 3.x line, so the hop that actually breaks apps (3.0.0's move to
Apple SDK 9) was never covered. This adds one section for the whole upgrade,
using the Migrating from versions < N.0.0 shape the Apple and Android SDK
guides use.

Two required steps aren't documented anywhere today:

• Fabric dependency provider — required since RN 0.76. Without it
  <RoktLayoutView> mounts as RCTUnimplementedViewComponentView and embedded
  placements silently never appear.
• android-rokt-kit must be declared explicitly — it's compileOnly here,
  so a 2.x app that reached Rokt through android-core alone still compiles and
  installs, then throws on the first MParticle.Rokt.* call.

It also notes that the Expo plugin writes import mParticle_Apple_SDK for Swift
AppDelegates without declaring the umbrella pod, so an Expo app with no
iosKits generates code that doesn't compile — documented here, worth a
follow-up fix.

Testing Plan

Docs only. Claims verified against the 2.9.2..3.3.3 diff, the podspecs,
android/build.gradle, plugin/src/, and sample/ios/Podfile.lock; the three
cross-links confirmed to resolve to real anchors on origin/main of the Apple
and Android guides. prettier and markdownlint pass.

Question for review: the two pre-existing sections are now largely subsumed by
this one — fold them in, or keep them as release-specific notes?

[cursor]

PR Summary

Low Risk
Documentation-only change to MIGRATING.md; no runtime or build configuration is modified in this PR.

Overview
Adds a Migrating from versions < 3.0.0 section to MIGRATING.md, framing the 2.9.x → current 3.x jump as one upgrade (Apple SDK 9, Android SDK 6, Rokt iOS 5.3) instead of leaving that break only in scattered 3.x release notes.

The new guide walks through platform setup: RN 0.76+ peer dependency, iOS 15.6 / Podfile and Expo expo-build-properties, CocoaPods changes for the ObjC/Swift pod split and Rokt pins, updated pre_install dynamic-framework pod list, and umbrella vs ObjC imports (including the Expo Swift AppDelegate / missing umbrella pod compile issue). It documents RN 0.77+ RCTAppDependencyProvider for Fabric/RoktLayoutView, removed AppDelegateProxy forwarding, and explicit android-rokt-kit Gradle dependency because the wrapper only has it as compileOnly.

It also lists behavior and API deltas integrators should re-check (setLocation on iOS, CommerceEvent.createProductActionEvent, RoktLayoutView layout, Rokt errors when the kit is missing, possible one-time queued-event loss) and new 3.x JS/Expo options. Existing lower sections on Android 6.0 and Rokt 9.3.1+ remain unchanged below the new block.

^{Reviewed by Cursor Bugbot for commit 92393c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

🟢 Approval recommended

Documentation-only change with one minor formatting issue identified and an inline fix suggested.

Pull request overview

Adds a consolidated 2.x → 3.x migration section to MIGRATING.md to cover the major breaking upgrade steps (notably the Apple SDK 9 move) that were previously only documented as incremental 3.x notes.

Changes:

• Introduces a new “Migrating from versions < 3.0.0” guide covering RN/iOS/Android upgrade prerequisites.
• Documents two previously undocumented upgrade pitfalls (Fabric dependency provider, explicit android-rokt-kit dependency).
• Adds links and notes to external Apple/Android SDK migration guides and known Expo plugin-generated iOS import/pod mismatch.

File summaries

File	Description
MIGRATING.md	Adds a full 2.x → 3.x migration section and clarifies key dependency/tooling requirements across iOS/Android/Expo.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.