Adds popscope migration guide

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

@@ -33,6 +33,7 @@ release, and listed in alphabetical order:
 
 ### Not yet released to stable
 
+* [Generic types in `PopScope`][]
 * [Rename `MaterialState` to `WidgetState`][]
 * [Introduce new `ColorScheme` roles][]
 * [Stop generating `AssetManifest.json`][]
@@ -43,6 +44,7 @@ release, and listed in alphabetical order:
 * [Deprecated API removed after v3.19][]
 * [Dropping support for Android KitKat][]
 
+[Generic types in `PopScope`]: /release/breaking-changes/popscope-with-result
 [Rename `MaterialState` to `WidgetState`]: /release/breaking-changes/material-state
 [Introduce new `ColorScheme` roles]: /release/breaking-changes/new-color-scheme-roles
 [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json

src/content/release/breaking-changes/popscope-with-result.md

@@ -0,0 +1,104 @@
+---
+title: Generic types in PopScope
+description: >
+  Added a generic type in PopScope class and updated the onPopInvoked
+  function signature.
+---
+
+## Summary
+
+Added a generic type in [`PopScope`][] class and updated the [`onPopInvoked`][]
+function signature to take in an additional result as an position parameter.
+
+## Context
+
+Previously, PopScope hadn't haven a way to access the pop result when `onPopInvoked`
+is called. To add support for accessing pop result, the generic type is added to
+PopScope class so that the `onPopInvoked` can access the type-safe result.
+
+## Description of change
+
+Added a generic type in `PopScope` class and updated the `onPopInvoked`
+function signature to take in an additional result as an position parameter.
+
+## Migration guide
+
+Code before migration
+
+```dart
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(
+    MaterialApp(
+      navigatorKey: nav,
+      home: PopScope(
+        canPop: false,
+        onPopInvoked: (bool didPop) {
+          if (didPop) {
+            return;
+          }
+          launchConfirmationDialog();
+        },
+        child: MyWidget(),
+      ),
+    ),
+  );
+}
+```
+
+Code after migration
+```dart
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(
+    MaterialApp(
+      navigatorKey: nav,
+      home: PopScope<Object?>(
+        canPop: false,
+        onPopInvoked: (bool didPop, Object? result) {
+          if (didPop) {
+            return;
+          }
+          launchConfirmationDialog();
+        },
+        child: MyWidget(),
+      ),
+    ),
+  );
+}
+```
+
+The generic type should match the generic type of the [`Route`] the `PopScope` is in.
+If the route uses `int` as its generic type, consider use `PopScope<int>`.
+
+If the widget are shared across multiple routes with different types, one can
+use `PopScope<Object?>` to catch all possible types.
+
+## Timeline
+
+Landed in version: TBD
+In stable release: TBD
+
+## References
+
+API documentation:
+
+* [`PopScope`][]
+* [`onPopInvoked`][]
+* [`Route`][]
+
+Relevant issue:
+
+* [Issue 137458][]
+
+Relevant PR:
+
+* [Add generic type for result in PopScope][]
+
+[Add generic type for result in PopScope]: {{site.repo.flutter}}/pull/139164
+[`PopScope`]: {{site.api}}/flutter/widgets/PopScope-class.html
+[`Route`]: {{site.api}}/flutter/widgets/Route-class.html
+[`onPopInvoked`]: {{site.api}}/flutter/widgets/PopScope/onPopInvoked.html
+[Issue 137458]: {{site.repo.flutter}}/issues/137458