docs: add a v2 to v3 migration guide

[spydon]

Closes SDK-1425

What

v3 is accumulating breaking changes across every package in the monorepo (#1278), and there is nowhere a user can look to find out what they have to change in their own code. The changelogs are per package, auto-generated and one line per commit, so anyone upgrading has to read seven of them and reconstruct the migration themselves. sdk-compliance.yaml tracks capabilities, not migrations.

This adds a MIGRATION.md at the repository root, modelled on Flame's migration guide:

• One section per major version step, newest first: ## Migrating from v2 to v3.
• One ### subsection per breaking change, titled after what changed.
• Each subsection says why the change was made and what you have to do, with a // Before / // After Dart snippet.
• Changes that keep their name but change type or behaviour are called out explicitly, since those do not surface as compile errors.

One file for the whole monorepo rather than one per package, because the packages go major in lockstep, and it gives us a single link to hand to users.

Covered so far

The two breaking commits that have landed on main:

• RealtimeClient.connectionState changing from String to SocketState? (refactor(realtime)!: clean up connection naming on RealtimeClient #1404). This is the silent one: the name is unchanged, so anyone comparing it against 'open' gets no compile error.
• The conn abbreviations spelled out: conn → connection, connState → connectionState, onConnMessage → onConnectionMessage (refactor(realtime)!: clean up connection naming on RealtimeClient #1404).
• The four consumer-reachable enum renames (refactor!: singularize plural enum names and fold enum extensions in #1654): SocketStates → SocketState, PostgresTypes → PostgresType, AuthenticatorAssuranceLevels → AuthenticatorAssuranceLevel, LoadTableSnapshots → TableSnapshotScope.

Left out on purpose: the three enums that were never exported (ChannelStates, ChannelEvents, RealtimeListenTypes) and the enum extensions folded in by #1654, since all of them are @internal and cannot break a consumer.

The section carries a note that v3 is unreleased and the list is still growing.

Keeping it current

AGENTS.md now states that a change breaking the public API adds its own section to MIGRATION.md in the same pull request, the same way parity work reconciles sdk-compliance.yaml. There is no pull request template in .github/, so there was nothing to add a checkbox to.

Linked from the root README.md and packages/supabase_flutter/README.md, next to the existing Guides and Reference Docs links.

Testing

Documentation only, no code changes. Every snippet in the guide was type-checked against the workspace in a scratch file (dart analyze, clean), which was then deleted.

[coderabbitai]

Warning

Review limit reached

@spydon, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 4 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4203e565-3c6d-4df6-9af4-d068c9fe523d

📥 Commits

Reviewing files that changed from the base of the PR and between a08b657 and f45741a.

📒 Files selected for processing (4)

• AGENTS.md
• MIGRATION.md
• README.md
• packages/supabase_flutter/README.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}