Update plugin migration instructions (#12591)

_Description of what this PR is changing or adding, and why:_

This change moves the plugin migration guide to the bottom so app
migrations are first.

This also adds a warning that plugin APIs are not available on stable
yet.

_Issues fixed by this PR (if any):_

_PRs or commits this PR depends on (if any):_

## Presubmit checklist

- [x] If you are unwilling, or unable, to sign the CLA, even for a
_tiny_, one-word PR, please file an issue instead of a PR.
- [x] If this PR is not meant to land until a future stable release,
mark it as draft with an explanation.
- [x] This PR follows the [Google Developer Documentation Style
Guidelines](https://developers.google.com/style)—for example, it doesn't
use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person
pronouns).
- [x] This PR uses [semantic line
breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks)
  of 80 characters or fewer.

---------

Co-authored-by: Shams Zakhour <[email protected]>

Author: vashworth

src/content/release/breaking-changes/uiscenedelegate.md

@@ -31,12 +31,12 @@ the following:
 To use the UIScene lifecycle with Flutter, migrate the following support:
 * All Flutter apps that support iOS - See the [migration guide for Flutter
   apps](/release/breaking-changes/uiscenedelegate/#migration-guide-for-flutter-apps)
-* Flutter plugins that use iOS application lifecycle events - See the [migration
-  guide for
-  plugins](/release/breaking-changes/uiscenedelegate/#migration-guide-for-flutter-plugins)
 * Flutter embedded in iOS native apps - See the [migration guide for adding
   Flutter to an existing
   app](/release/breaking-changes/uiscenedelegate/#migration-guide-for-adding-flutter-to-existing-app-add-to-app)
+* Flutter plugins that use iOS application lifecycle events - See the [migration
+  guide for
+  plugins](/release/breaking-changes/uiscenedelegate/#migration-guide-for-flutter-plugins)
 
 Migrating to UIScene shifts the AppDelegate's role—the UI lifecycle is
 now handled by the UISceneDelegate. The AppDelegate
@@ -270,121 +270,6 @@ For Objective-C projects, create a `SceneDelegate.h` and `SceneDelegate.m`:
 Info.plist from `FlutterSceneDelegate` to
 `$(PRODUCT_MODULE_NAME).SceneDelegate`.
 
-## Migration guide for Flutter plugins
-
-Not all plugins use lifecycle events. If your plugin does, though, you will
-need to migrate to UIKit's scene-based lifecycle.
-
-1. Adopt the `FlutterSceneLifeCycleDelegate` protocol
-
-```swift diff
-- public final class MyPlugin: NSObject, FlutterPlugin {
-+ public final class MyPlugin: NSObject, FlutterPlugin, FlutterSceneLifeCycleDelegate {
-```
-
-```objc diff
-- @interface MyPlugin : NSObject<FlutterPlugin>
-+ @interface MyPlugin : NSObject<FlutterPlugin, FlutterSceneLifeCycleDelegate>
-```
-
-2. Registers the plugin as a receiver of `UISceneDelegate` calls.
-
-To continue supporting apps that have not migrated to the UIScene lifecycle yet,
-you might consider remaining registered to the App Delegate and keeping the App
-Delegate events as well.
-
-```swift diff
-  public static func register(with registrar: FlutterPluginRegistrar) {
-    ...
-    registrar.addApplicationDelegate(instance)
-+   registrar.addSceneDelegate(instance)
-  }
-```
-
-```objc diff
-  + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
-    ...
-    [registrar addApplicationDelegate:instance];
-+   [registrar addSceneDelegate:instance];
-  }
-```
-
-3. Add one or more of the following scene events that are needed for your
-plugin.
-
-Most App Delegate UI events have a 1-to-1 replacement. To see details on each
-event, visit Apple's documentation on
-[UISceneDelegate]({{site.apple-dev}}/documentation/uikit/uiscenedelegate)
-and
-[UIWindowSceneDelegate]({{site.apple-dev}}/documentation/uikit/uiwindowscenedelegate).
-
-
-```swift
-public func scene(
-  _ scene: UIScene,
-  willConnectTo session: UISceneSession,
-  options connectionOptions: UIScene.ConnectionOptions?
-) -> Bool { }
-
-public func sceneDidDisconnect(_ scene: UIScene) { }
-
-public func sceneWillEnterForeground(_ scene: UIScene) { }
-
-public func sceneDidBecomeActive(_ scene: UIScene) { }
-
-public func sceneWillResignActive(_ scene: UIScene) { }
-
-public func sceneDidEnterBackground(_ scene: UIScene) { }
-
-public func scene(
-    _ scene: UIScene,
-    openURLContexts URLContexts: Set<UIOpenURLContext>
-  ) -> Bool { }
-
-public func scene(_ scene: UIScene, continue userActivity: NSUserActivity)
-    -> Bool { }
-
-public func windowScene(
-    _ windowScene: UIWindowScene,
-    performActionFor shortcutItem: UIApplicationShortcutItem,
-    completionHandler: @escaping (Bool) -> Void
-  ) -> Bool { }
-```
-
-```objc
-- (BOOL)scene:(UIScene*)scene
-    willConnectToSession:(UISceneSession*)session
-                 options:(nullable UISceneConnectionOptions*)connectionOptions;
-
-- (void)sceneDidDisconnect:(UIScene*)scene { }
-
-- (void)sceneWillEnterForeground:(UIScene*)scene { }
-
-- (void)sceneDidBecomeActive:(UIScene*)scene { }
-
-- (void)sceneWillResignActive:(UIScene*)scene { }
-
-- (void)sceneDidEnterBackground:(UIScene*)scene { }
-
-- (BOOL)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts { }
-
-- (BOOL)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity { }
-
-- (BOOL)windowScene:(UIWindowScene*)windowScene
-    performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
-               completionHandler:(void (^)(BOOL succeeded))completionHandler { }
-```
-
-4. Move launch logic from `application:willFinishLaunchingWithOptions:` and
-`application:didFinishLaunchingWithOptions:` to
-`scene:willConnectToSession:options:`.
-
-Despite `application:willFinishLaunchingWithOptions:` and
-`application:didFinishLaunchingWithOptions:` not being deprecated, after
-migrating to UIScene lifecycle, the launch options will be `nil`. Any logic
-performed here related to the launch options should be moved to the
-`scene:willConnectToSession:options:` event.
-
 ## Migration guide for adding Flutter to existing app (Add to App)
 
 Similar to the `FlutterAppDelegate`, the `FlutterSceneDelgate` is recommended
@@ -689,6 +574,137 @@ sceneLifeCycleDelegate.unregisterSceneLifeCycle(with: flutterEngine)
 [self.sceneLifeCycleDelegate unregisterSceneLifeCycleWithFlutterEngine:self.flutterEngine];
 ```
 
+## Migration guide for Flutter plugins
+
+Not all plugins use lifecycle events. If your plugin does, though, you will
+need to migrate to UIKit's scene-based lifecycle.
+
+1. Update the Dart and Flutter SDK versions in your pubspec.yaml
+
+```yaml
+environment:
+  sdk: ^3.10.0-290.1.beta
+  flutter: ">=3.38.0-0.1.pre"
+```
+
+:::warning
+The below Flutter APIs are available in the 3.38.0-0.1.pre beta, but are not
+yet available on stable. You might consider publishing a
+[prerelease](https://dart.dev/tools/pub/publishing#publishing-prereleases) or
+[preview](https://dart.dev/tools/pub/publishing#publish-preview-versions)
+version of your plugin to migrate early.
+:::
+
+2. Adopt the `FlutterSceneLifeCycleDelegate` protocol
+
+```swift diff
+- public final class MyPlugin: NSObject, FlutterPlugin {
++ public final class MyPlugin: NSObject, FlutterPlugin, FlutterSceneLifeCycleDelegate {
+```
+
+```objc diff
+- @interface MyPlugin : NSObject<FlutterPlugin>
++ @interface MyPlugin : NSObject<FlutterPlugin, FlutterSceneLifeCycleDelegate>
+```
+
+3. Registers the plugin as a receiver of `UISceneDelegate` calls.
+
+To continue supporting apps that have not migrated to the UIScene lifecycle yet,
+you might consider remaining registered to the App Delegate and keeping the App
+Delegate events as well.
+
+```swift diff
+  public static func register(with registrar: FlutterPluginRegistrar) {
+    ...
+    registrar.addApplicationDelegate(instance)
++   registrar.addSceneDelegate(instance)
+  }
+```
+
+```objc diff
+  + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
+    ...
+    [registrar addApplicationDelegate:instance];
++   [registrar addSceneDelegate:instance];
+  }
+```
+
+4. Add one or more of the following scene events that are needed for your
+plugin.
+
+Most App Delegate UI events have a 1-to-1 replacement. To see details for each
+event, visit Apple's documentation on
+[`UISceneDelegate`][] and [`UIWindowSceneDelegate`][].
+
+[`UISceneDelegate`]: {{site.apple-dev}}/documentation/uikit/uiscenedelegate
+[`UIWindowSceneDelegate`]: {{site.apple-dev}}/documentation/uikit/uiwindowscenedelegate
+
+
+```swift
+public func scene(
+  _ scene: UIScene,
+  willConnectTo session: UISceneSession,
+  options connectionOptions: UIScene.ConnectionOptions?
+) -> Bool { }
+
+public func sceneDidDisconnect(_ scene: UIScene) { }
+
+public func sceneWillEnterForeground(_ scene: UIScene) { }
+
+public func sceneDidBecomeActive(_ scene: UIScene) { }
+
+public func sceneWillResignActive(_ scene: UIScene) { }
+
+public func sceneDidEnterBackground(_ scene: UIScene) { }
+
+public func scene(
+    _ scene: UIScene,
+    openURLContexts URLContexts: Set<UIOpenURLContext>
+  ) -> Bool { }
+
+public func scene(_ scene: UIScene, continue userActivity: NSUserActivity)
+    -> Bool { }
+
+public func windowScene(
+    _ windowScene: UIWindowScene,
+    performActionFor shortcutItem: UIApplicationShortcutItem,
+    completionHandler: @escaping (Bool) -> Void
+  ) -> Bool { }
+```
+
+```objc
+- (BOOL)scene:(UIScene*)scene
+    willConnectToSession:(UISceneSession*)session
+                 options:(nullable UISceneConnectionOptions*)connectionOptions { }
+
+- (void)sceneDidDisconnect:(UIScene*)scene { }
+
+- (void)sceneWillEnterForeground:(UIScene*)scene { }
+
+- (void)sceneDidBecomeActive:(UIScene*)scene { }
+
+- (void)sceneWillResignActive:(UIScene*)scene { }
+
+- (void)sceneDidEnterBackground:(UIScene*)scene { }
+
+- (BOOL)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)URLContexts { }
+
+- (BOOL)scene:(UIScene*)scene continueUserActivity:(NSUserActivity*)userActivity { }
+
+- (BOOL)windowScene:(UIWindowScene*)windowScene
+    performActionForShortcutItem:(UIApplicationShortcutItem*)shortcutItem
+               completionHandler:(void (^)(BOOL succeeded))completionHandler { }
+```
+
+5. Move launch logic from `application:willFinishLaunchingWithOptions:` and
+`application:didFinishLaunchingWithOptions:` to
+`scene:willConnectToSession:options:`.
+
+Despite `application:willFinishLaunchingWithOptions:` and
+`application:didFinishLaunchingWithOptions:` not being deprecated, after
+migrating to the `UIScene` lifecycle, the launch options will be `nil`. Any logic
+performed here related to the launch options should be moved to the
+`scene:willConnectToSession:options:` event.
 
 ## Bespoke FlutterViewController usage