Added UISceneDelegate breaking change notice. #12082

gaaclarke · 2025-05-29T22:38:15Z

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

Adding breaking change notice for UISceneDelegate adoption.

Issues fixed by this PR (if any):

flutter/flutter#167267

PRs or commits this PR depends on (if any):

flutter/flutter#169365

Presubmit checklist

This PR is marked as draft with an explanation if not meant to land until a future stable release.
This PR doesn’t contain automatically generated corrections (Grammarly or similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

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

Co-authored-by: Victoria Ashworth <15619084+vashworth@users.noreply.github.com>

gaaclarke

I removed the storyboard recommendation as discussed in the chat.

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

flutter-website-bot · 2025-05-30T20:51:02Z

Visit the preview URL for this PR (updated for commit e875e96):

https://flutter-docs-prod--pr12082-uiscenedelegate-bjp0wxxs.web.app

gaaclarke · 2025-05-30T22:09:34Z

I'm not quite sure what's breaking about my png. This seems to be following the pattern in src/content/release/breaking-changes/rendering-changes.md. The PR that introduced that though has 1600 files changed so I don't know if there is some magic I'm missing. It renders locally fine. Maybe @Sfshaza can guide me when her team gets around to reviewing it.

vashworth · 2025-06-02T17:14:51Z

I'm not quite sure what's breaking about my png. This seems to be following the pattern in src/content/release/breaking-changes/rendering-changes.md. The PR that introduced that though has 1600 files changed so I don't know if there is some magic I'm missing. It renders locally fine. Maybe @Sfshaza can guide me when her team gets around to reviewing it.

Looks like images usually go under
https://github.com/flutter/website/tree/7822f909bacacb37e926b098b1183885eaa85f97/src/content/assets/images

and then they're referenced like

![adding ads](/assets/images/docs/add-payments.png)

sfshaza2

Sorry, it's still in draft and I edited it like it was out of draft. :)

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

sfshaza2 · 2025-06-02T18:27:25Z

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

+
+- Landed in main: TBD
+- Landed in stable: TBD
+- Unknown: Apple changes their warning to an assert and Flutter apps that


Meaning that we don't know when this change will occur? Do we know what the Apple release number will be? Like iOS 20?

No, it's not communicated when it will happen.

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

sfshaza2 · 2025-06-02T18:45:27Z

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

+{% endtab %}
+{% endtabs %}
+
+Set up the `FlutterPluginRegistrant` programmatically through the


What is this sentence doing here? It seems out of place.

It's describing what is happening in the code blocks. Would you like to see it before the code?

Yeah, that would be better, but it's not worth holding this PR up if folks are running into thi problem.

sfshaza2 · 2025-06-02T19:04:51Z

@parlough, Aaron added a screenshot to this breaking change. He put it in the assets subdirectory, under the breaking changes directory, which seems fine, and is done with other breaking changes. However, the build is breaking because it can't find the image. Might this be because of that old situation where you must put the image in place in a separate PR before referring to it? I only wonder that because the image isn't in our usual place for assets, but we've certainly done this with other breaking changes.

sfshaza2 · 2025-06-02T19:08:41Z

@gaaclarke, I edited this more dramatically than usual, and that is because of the references to "users", which I find confusing. You mean "users of the API", or "developers". But, in actual reality, its the app's behavior that we care about, so I just removed most (all?) references to "users", rather than change them to "developers" or (better still) "you".

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

parlough · 2025-06-03T08:17:03Z

However, the build is breaking because it can't find the image.

I can move the image to the root directory, but I think this is more clean if we keep the image next to the markdown that uses it.

For some future infra changes, I'd prefer if we kept images in the shared /assets directory so thanks for moving it to there! Looks to be working with that change :)

I pushed some minor formatting consistency cleanup, but otherwise this looks good to me. Thanks!

gaaclarke · 2025-06-03T15:43:36Z

@sfshaza2 do we want to land this now that it's on main. I see there are some other entries not associated with a stable release. Or do we want to wait until it hits stable. It might be worth waiting a few more days to make sure it sticks. There is still a small question about making a minor convenience API change that we are looking at.

gaaclarke · 2025-06-04T22:46:30Z

I'm getting pings on github where users are running into this on main. It's probably worthwhile to get this landed, friendly ping.

sfshaza2

lgtm

… usage (#12095) ## _Description of what this PR is changing or adding, and why:_ Updating platform channel guidance to be inline with the breaking change: #12082 ## _Issues fixed by this PR (if any):_ ## _PRs or commits this PR depends on (if any):_ flutter/flutter#169365 #12082 ## Presubmit checklist - [x] This PR is marked as draft with an explanation if not meant to land until a future stable release. - [x] This PR doesn’t contain automatically generated corrections (Grammarly or similar). - [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). - [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.

stuartmorgan-g · 2025-06-09T15:55:14Z

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

+  func register(with registry: any FlutterPluginRegistry) {
+    let registrar = registry.registrar(forPlugin: "battery")
+    let batteryChannel = FlutterMethodChannel(name: "samples.flutter.dev/battery",
+                                              binaryMessenger: registrar.messenger)


This Swift code does not compile. registry.registrar(forPlugin: "battery") returns a nullable value, so registrar is a FlutterPluginRegistrar?, and can't have methods called on it without unwrapping. This seems like a serious problem, because it's not clear how a Flutter app developer should if/when it's safe to assume they can actually unwrap it, or what they should do it a null check on it fails and they have critical logic that relies on it existing.

Also, it has to be messenger(), because on iOS messenger isn't declared as a property.

Here is the example code that accompanied the change: https://github.com/flutter/flutter/blob/master/examples/platform_channel_swift/ios/Runner/AppDelegate.swift

We should update it to match the example, give that a look.

stuartmorgan-g · 2025-06-09T15:57:39Z

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

+  }
+
+  func register(with registry: any FlutterPluginRegistry) {
+    let registrar = registry.registrar(forPlugin: "battery")


Why are we forcing applications to pretend they are plugins? Couldn't the engine make a registrar internally, and the protocol apps implement give them a registrant, rather than a registry?

This is not just awkward, it's also dangerous. If the name the developer picks for this arbitrary-to-them string collides with an actual plugin's registry, Bad Things will happen.

Was there a design doc for this new system?

Was there a design doc for this new system?

Yes, this was discussed quite a bit and there is a section for it in the design doc: https://docs.google.com/document/d/1ZfcQOs-UKRa9jsFG84-MTFeibZTLKCvPQLxF2eskx44/edit?tab=t.0

This is not just awkward, it's also dangerous. If the name the developer picks for this arbitrary-to-them string collides with an actual plugin's registry, Bad Things will happen.

Bad things like the registrar returns nil? That's unfortunately inherent to the design of the plugins. We could provide a better example for plugin names, "flutter.dev/battery"?

Bad things like the registrar returns nil?

Bad things like:

It will NSAssert in debug mode

One of the registrars will be stomped in the engine's mapping, causing any future interactions with the registry to have unexpected behavior, with the exact behavior depending on the order of operations in engine logic.

That's unfortunately inherent to the design of the plugins.

Not really. Actual plugins don't rely on individual developers to pick magic strings, we auto-generate them in the tool, where we can centrally control the set of strings and avoid collisions.

We could provide a better example for plugin names, "flutter.dev/battery"?

The fundamental problem is that this isn't a plugin. I think we should address the fact that we are requiring developers to give something that isn't a plugin a "plugin name" in the first place.

Added UISceneDelegate breaking change notice.

262adc7

gaaclarke requested a review from vashworth May 29, 2025 22:38

vashworth reviewed May 30, 2025

View reviewed changes

gaaclarke and others added 3 commits May 30, 2025 10:19

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

a9d9af4

Co-authored-by: Victoria Ashworth <15619084+vashworth@users.noreply.github.com>

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

fd6c7c9

Co-authored-by: Victoria Ashworth <15619084+vashworth@users.noreply.github.com>

victoria feedback

af2fde3

gaaclarke commented May 30, 2025

View reviewed changes

gaaclarke requested a review from vashworth May 30, 2025 20:26

vashworth reviewed May 30, 2025

View reviewed changes

src/content/release/breaking-changes/uiscenedelegate.md Outdated Show resolved Hide resolved

switched to xml

3b3c92a

fixed link

4b04f8d

sfshaza2 reviewed Jun 2, 2025

View reviewed changes

gaaclarke and others added 11 commits June 2, 2025 13:23

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

6dbeae6

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

49f96e7

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

1c1dbe8

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

85e6586

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

6993a2b

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

77cf8e7

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

ebd0cf9

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

3e98479

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

59099c0

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

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

29fba38

Co-authored-by: Shams Zakhour (ignore Sfshaza) <44418985+sfshaza2@users.noreply.github.com>

format and shams feedback

5644b70

This comment was marked as outdated.

Sign in to view

moved plist image to root asset directory

da5e72a

gaaclarke requested review from sfshaza2 and vashworth June 2, 2025 21:47

gaaclarke mentioned this pull request Jun 2, 2025

Updated the platform channel recommendations to match uiscenedelegate usage #12095

Merged

4 tasks

parlough added 3 commits June 3, 2025 16:01

Merge branch 'main' into uiscenedelegate

590d80b

Optimize image

497e6e3

Minor formatting cleanup

ba4aa05

updated swift signature

e875e96

gaaclarke mentioned this pull request Jun 4, 2025

[ios]: Warning for FlutterAppDelegate.window.rootViewController in launch functions flutter/flutter#169166

Merged

9 tasks

sfshaza2 approved these changes Jun 4, 2025

View reviewed changes

sfshaza2 marked this pull request as ready for review June 4, 2025 23:31

sfshaza2 requested review from a team, antfitch and parlough as code owners June 4, 2025 23:31

sfshaza2 merged commit 72d916c into flutter:main Jun 4, 2025
9 checks passed

vashworth mentioned this pull request Jun 6, 2025

☂ Adopting UIScene lifecycle in Flutter flutter/flutter#170171

Open

stuartmorgan-g reviewed Jun 9, 2025

View reviewed changes

Added UISceneDelegate breaking change notice. #12082

Added UISceneDelegate breaking change notice. #12082

Uh oh!

Conversation

gaaclarke commented May 29, 2025

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

Issues fixed by this PR (if any):

PRs or commits this PR depends on (if any):

Presubmit checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaaclarke left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

flutter-website-bot commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gaaclarke commented May 30, 2025

Uh oh!

vashworth commented Jun 2, 2025

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sfshaza2 commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sfshaza2 commented Jun 2, 2025

Uh oh!

This comment was marked as outdated.

parlough commented Jun 3, 2025

Uh oh!

gaaclarke commented Jun 3, 2025

Uh oh!

gaaclarke commented Jun 4, 2025

Uh oh!

sfshaza2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

flutter-website-bot commented May 30, 2025 •

edited

Loading

sfshaza2 commented Jun 2, 2025 •

edited

Loading

stuartmorgan-g Jun 9, 2025 •

edited

Loading