Predictive back transition breaking change announcement (#12268)

This PR spawned out of
flutter/flutter#165832 (comment).
That PR will change the default page transition and turn on predictive
back by default. While there is no API breakage, users may encounter
test breakages in tests that indirectly depend on the default page
transition and/or its duration. Several of these kinds of breakages were
encountered in flutter/flutter#165832 in the
framework tests, customer tests, and Google tests.

This PR should explain:

 * What predictive back is.
 * How to make sure an app supports predictive back.
 * What the new Fade Fowards page transition looks like.
 * How to manually change the page transition back to the old one.
* How to write tests that don't depend on the page transition and its
duration.

_Issues fixed by this PR (if any):_ n/a

_PRs or commits this PR depends on (if any):_
flutter/flutter#165832

## 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]>
Co-authored-by: Parker Lougheed <[email protected]>

Author: 3 people

src/content/release/breaking-changes/default-android-page-transition.md

@@ -0,0 +1,215 @@
+---
+title: The default page transition on Android is now PredictiveBackPageTransitionsBuilder
+description: >-
+  Android's default page transition has been updated to match the
+  platform and to support predictive back.
+---
+
+## Summary
+
+The default page transition on Android has been updated from
+[`ZoomPageTransitionsBuilder`][] to [`PredictiveBackPageTransitionsBuilder`][].
+When not using predictive back, this falls back to
+[`FadeForwardsPageTransitionsBuilder`][].
+
+## Context
+
+Android has been rolling out a feature called predictive back, where performing
+a back gesture allows the user to peek at the previous route or app and possibly
+cancel the navigation. Flutter added support for this with the [`PopScope`][]
+widget followed by [`PredictiveBackPageTransitionsBuilder`][].
+
+In the meantime, Android also updated its default page transition. Flutter added
+support for this with [`FadeForwardsPageTransitionsBuilder`][].
+
+## Description of change
+
+With this change, [`PredictiveBackPageTransitionsBuilder`][] has replaced
+[`ZoomPageTransitionsBuilder`][] as the default page transition on Android.
+During a normal page transition without a predictive back gesture, users
+see the new [`FadeForwardsPageTransitionsBuilder`][] as the default page
+transition. When using a predictive back gesture, the page animates along
+with the gesture and allows canceling or committing to the back navigation.
+
+In this example, no page transition is explicitly given, so the
+[default]({{site.github}}/flutter/flutter/blob/e983e4bd81f29b17215057fa5c9f46f96cbaf183/packages/flutter/lib/src/material/page_transitions_theme.dart#L806-L813)
+is set to [`PredictiveBackPageTransitionsBuilder`][] in the theme on Android.
+
+```dart
+MaterialApp(
+  theme: ThemeData(
+    brightness: Brightness.light,
+  ),
+  home: const PageOne(),
+);
+```
+
+## Migration guide
+
+If you want to keep your app's page transition on the old
+[`ZoomPageTransitionsBuilder`][], you can simply set your page transition
+explicitly in your app's theme. Keep in mind that you will not be able to
+support predictive back route transitions.
+
+Code before migration:
+
+```dart
+return MaterialApp(
+  theme: ThemeData(
+    brightness: Brightness.light,
+    // pageTransitionsTheme is the default.
+  ),
+  home: const MyFirstScreen(),
+);
+```
+
+Code after migration:
+
+```dart
+MaterialApp(
+  theme: ThemeData(
+    // pageTransitionsTheme is explicitly set to the old transition on Android.
+    pageTransitionsTheme: const PageTransitionsTheme(
+      builders: {
+        TargetPlatform.android: ZoomPageTransitionsBuilder(),
+      },
+    ),
+  ),
+  home: const MyFirstScreen(),
+);
+```
+
+One side effect of changing the default transition is that the duration that it
+takes to transition between pages has increased from 300ms to 450ms. This might
+cause breakages in tests that depend on the previous transition duration.
+Fortunately, it's possible to use [`TransitionDurationObserver`][] to keep tests
+independent of whatever page transition is used.
+
+Code before migration:
+
+```dart
+testWidgets('example', (WidgetTester tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      onGenerateRoute: (RouteSettings settings) { ... },
+    ),
+  );
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsNothing);
+
+  // Pump through the whole transition, hardcoded to 300ms.
+  await tester.tap(find.text('Next'));
+  await tester.pump(const Duration(milliseconds: 300));
+
+  expect(find.text('Page 1'), findsNothing);
+  expect(find.text('Page 2'), findsOneWidget);
+});
+```
+
+Code after migration:
+
+```dart
+testWidgets('example', (WidgetTester tester) async {
+  final TransitionDurationObserver observer = TransitionDurationObserver();
+
+  await tester.pumpWidget(
+    MaterialApp(
+      navigatorObservers: <NavigatorObserver>[observer],
+      onGenerateRoute: (RouteSettings settings) { ... },
+    ),
+  );
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsNothing);
+
+  // Pump through the whole transition independent of the duration.
+  await tester.tap(find.text('Next'));
+  await observer.pumpPastTransition(tester);
+
+  expect(find.text('Page 1'), findsNothing);
+  expect(find.text('Page 2'), findsOneWidget);
+});
+```
+
+It's even possible to write tests that need to pump part of the way through a
+page transition without depending on the exact duration.
+
+Code before migration:
+
+```dart
+testWidgets('example', (WidgetTester tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      onGenerateRoute: (RouteSettings settings) { ... },
+    ),
+  );
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsNothing);
+
+  // Pump through half of the transition with a hardcoded value.
+  await tester.tap(find.text('Back'));
+  await tester.pump(const Duration(milliseconds: 150));
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsOneWidget);
+});
+```
+
+Code after migration:
+
+```dart
+testWidgets('example', (WidgetTester tester) async {
+  final TransitionDurationObserver observer = TransitionDurationObserver();
+
+  await tester.pumpWidget(
+    MaterialApp(
+      navigatorObservers: <NavigatorObserver>[observer],
+      onGenerateRoute: (RouteSettings settings) { ... },
+    ),
+  );
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsNothing);
+
+  // Pump through half of the transition independent of the duration.
+  await tester.tap(find.text('Back'));
+  await tester.pump(observer.transitionDuration ~/ 2);
+
+  expect(find.text('Page 1'), findsOneWidget);
+  expect(find.text('Page 2'), findsOneWidget);
+});
+```
+
+## Timeline
+
+Landed in version: 3.37.0-0.0.pre<br>
+In stable release: 3.38.0
+
+## References
+
+API documentation:
+
+* [`ZoomPageTransitionsBuilder`][]
+* [`PredictiveBackPageTransitionsBuilder`][]
+* [`FadeForwardsPageTransitionsBuilder`][]
+* [`PopScope`][]
+* [`TransitionDurationObserver`][]
+
+Relevant issues:
+
+* [Android predictive back route transitions][]
+
+Relevant PRs:
+
+* [Predictive back route transitions by default][]
+
+[`FadeForwardsPageTransitionsBuilder`]: {{site.api}}/flutter/material/FadeForwardsPageTransitionsBuilder-class.html
+[`PopScope`]: {{site.api}}/flutter/widgets/PopScope-class.html
+[`PredictiveBackPageTransitionsBuilder`]: {{site.api}}/flutter/material/PredictiveBackPageTransitionsBuilder-class.html
+[`TransitionDurationObserver`]: {{site.api}}/flutter/flutter_test/TransitionDurationObserver-class.html
+[`ZoomPageTransitionsBuilder`]: {{site.api}}/flutter/material/ZoomPageTransitionsBuilder-class.html
+
+[Android predictive back route transitions]: {{site.github.com}}/flutter/flutter/issues/131961
+[Predictive back route transitions by default]: {{site.github}}/flutter/flutter/pull/165832

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

@@ -55,11 +55,13 @@ They're sorted by release and listed in alphabetical order:
 * [Deprecate `OverlayPortal.targetsRootOverlay`][]
 * [Deprecate `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable`][]
 * [SnackBar with action no longer auto-dismisses][]
+* [The default page transition on Android is now `PredictiveBackPageTransitionBuilder`][]
 
 [`CupertinoDynamicColor` wide gamut support]: /release/breaking-changes/wide-gamut-cupertino-dynamic-color
 [Deprecate `OverlayPortal.targetsRootOverlay`]: /release/breaking-changes/deprecate-overlay-portal-targets-root
 [Deprecate `SemanticsProperties.focusable` and `SemanticsConfiguration.isFocusable`]: /release/breaking-changes/deprecate-focusable
 [SnackBar with action no longer auto-dismisses]: /release/breaking-changes/snackbar-with-action-behavior-update
+[The default page transition on Android is now `PredictiveBackPageTransitionBuilder`]: /release/breaking-changes/default-android-page-transition
 
 <a id="released-in-flutter-335" aria-hidden="true"></a>
 ### Released in Flutter 3.35