Merge branch 'main' into feat/jaspr-migration

Author: parlough

site/web/assets/images/docs/breaking-changes/uiscene-new-file.png

@@ -47,9 +47,28 @@ UIKit won't call AppDelegate methods related to UI state.
 
 ## Migration guide for Flutter apps
 
-The Flutter CLI will automatically migrate your app when you run `flutter run`
-or `flutter build ios` if your AppDelegate has not been customized. Otherwise,
-you must migrate manually.
+### Auto-Migrate (Experimental)
+
+The Flutter CLI can automatically migrate your app if your AppDelegate has not
+been customized.
+
+1. Enable UIScene Migration Feature
+
+```console
+flutter config --enable-uiscene-migration
+```
+
+2. Build or run your app
+
+```console
+flutter run
+or
+flutter build ios
+```
+
+If the migration succeeds, you will see a log that says "Finished migration to
+UIScene lifecycle". Otherwise, it warns you to migrate manually using the
+included instructions. If the migration succeeds, no further action is required!
 
 ### Migrate AppDelegate
 
@@ -206,6 +225,50 @@ As XML:
 </dict>
 ```
 
+### Create a SceneDelegate (Optional)
+
+If you need access to the `SceneDelegate`, you can create one by
+subclassing `FlutterSceneDelegate`.
+
+1. Open your app in Xcode
+2. Right click the **Runner** folder and select **New Empty File**
+
+![New Empty File option in Xcode](/assets/images/docs/breaking-changes/uiscene-new-file.png)
+
+For Swift projects, create a `SceneDelegate.swift`:
+
+```swift title=my_app/ios/Runner/SceneDelegate.swift
+import Flutter
+import UIKit
+
+class SceneDelegate: FlutterSceneDelegate {
+
+}
+```
+
+For Objective-C projects, create a `SceneDelegate.h` and `SceneDelegate.m`:
+
+```objc title=my_app/ios/Runner/SceneDelegate.h
+#import <Flutter/Flutter.h>
+#import <UIKit/UIKit.h>
+
+@interface SceneDelegate : FlutterSceneDelegate
+
+@end
+```
+
+```objc title=my_app/ios/Runner/SceneDelegate.m
+#import "SceneDelegate.h"
+
+@implementation SceneDelegate
+
+@end
+```
+
+3. Change the "Delegate Class Name" (`UISceneDelegateClassName`) in the
+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