Add breaking change page for completing Navigator behavior (#11684)

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

A breaking change is planned along the PR bellow.

_Issues fixed by this PR (if any):_

flutter/flutter#157505

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

flutter/flutter#157725

## 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.

---------

Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>

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

@@ -34,6 +34,8 @@ They're sorted by release and listed in alphabetical order:
 
 ### Not yet released to stable
 
+* [Deprecate `RouteTransitionRecord.markForRemove`][deprecate-markForRemove]
+   in favor of `RouteTransitionRecord.markForComplete`
 * [Deprecate `WebGoldenComparator`][]
 * [Deprecate `TextField.canRequestFocus`][]
 * [Deprecate `ThemeData.dialogBackgroundColor` in favor of `DialogThemeData.backgroundColor`][]
@@ -45,6 +47,7 @@ They're sorted by release and listed in alphabetical order:
 * [Updated Material 3 progress indicators][]
 * [`.flutter-plugins-dependencies` replaces `.flutter-plugins`][]
 
+[deprecate-markForRemove]: /release/breaking-changes/navigator-complete-route
 [Deprecate `WebGoldenComparator`]: /release/breaking-changes/web-golden-comparator
 [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus
 [Deprecate `ThemeData.dialogBackgroundColor` in favor of `DialogThemeData.backgroundColor`]: /release/breaking-changes/deprecate-themedata-dialogbackgroundcolor

src/content/release/breaking-changes/navigator-complete-route.md

@@ -0,0 +1,69 @@
+---
+title: When a route is removed from the stack, associated futures must complete
+description: >
+  Before this breaking change, routes created by Navigator and awaited for
+  results could never complete if the route was removed instead of popped.
+---
+
+## Summary
+
+When routes are pushed, developers can await them to be notified when they are
+popped. However, this didn't work when they were removed because the associated
+future was never completed.
+
+## Context
+
+All Navigator methods that call `remove` had this issue. By using `complete`,
+the issue is properly resolved, allowing developers to pass a result.
+
+## Description of change
+
+All Navigator methods have been updated to no longer call `remove` but instead
+use `complete`. Context menus are now built from the `contextMenuBuilder`
+parameter.
+
+All methods that directly use `complete` now accept an optional `result`
+parameter to return it to the associated future. Other methods that indirectly
+use `remove` currently return `null`. In the future, we might extend these
+methods with an optional callback function to allow developers to handle pop
+logic in indirect scenarios (such as `removeUntil`).
+
+Before this PR, methods bellow can't return a result :
+```dart
+Navigator.of(context).removeRoute(route);
+Navigator.of(context).removeRouteBelow(route);
+```
+
+After this PR, methods can return a result :
+```dart
+Navigator.of(context).removeRoute(route, result);
+Navigator.of(context).removeRouteBelow(route, result);
+```
+
+## Migration guide
+
+If you implemented `RouteTransitionRecord` and used `markForRemove`,
+you need to use `markForComplete` instead. `markForRemove` is now deprecated.
+
+For other developers, no changes are required. The navigator continues to work
+as expected with new capabilities.
+
+## Timeline
+
+Landed in version: 3.27.0-1.0.pre.39922  
+In stable release: X.X.X
+
+## References
+
+### API documentation:
+
+* [`RouteTransitionRecord`]({{site.api}}/flutter/widgets/RouteTransitionRecord-class.html)
+* [`Navigator`]({{site.api}}/flutter/widgets/Navigator-class.html)
+
+### Relevant issues:
+
+* [removeRoute unresolved future]({{site.repo.flutter}}/issues/157505)
+
+### Relevant PRs:
+
+* [feat: removeRoute now calls didComplete]({{site.repo.flutter}}/pull/157725)