From 9c8ee4fab690d3abf03556eeb24a90d17f479eb7 Mon Sep 17 00:00:00 2001
From: Ian Hickson <ian@hixie.ch>
Date: Wed, 19 Jul 2023 17:41:51 -0700
Subject: [PATCH] Document that you can't change initialRoute usefully
 (#130450)

Fixes https://github.com/flutter/flutter/issues/12454
---
 packages/flutter/lib/src/widgets/app.dart       | 4 ++++
 packages/flutter/lib/src/widgets/navigator.dart | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/packages/flutter/lib/src/widgets/app.dart b/packages/flutter/lib/src/widgets/app.dart
index c641566c384..af5d404c430 100644
--- a/packages/flutter/lib/src/widgets/app.dart
+++ b/packages/flutter/lib/src/widgets/app.dart
@@ -725,6 +725,10 @@ class WidgetsApp extends StatefulWidget {
   /// [routes], [onGenerateRoute], or [onUnknownRoute]); if they are not,
   /// [initialRoute] must be null and [builder] must not be null.
   ///
+  /// Changing the [initialRoute] will have no effect, as it only controls the
+  /// _initial_ route. To change the route while the application is running, use
+  /// the [Navigator] or [Router] APIs.
+  ///
   /// See also:
   ///
   ///  * [Navigator.initialRoute], which is used to implement this property.
diff --git a/packages/flutter/lib/src/widgets/navigator.dart b/packages/flutter/lib/src/widgets/navigator.dart
index 353b0614fcc..43156aa44e2 100644
--- a/packages/flutter/lib/src/widgets/navigator.dart
+++ b/packages/flutter/lib/src/widgets/navigator.dart
@@ -1470,6 +1470,10 @@ class Navigator extends StatefulWidget {
   ///
   /// The value is interpreted according to [onGenerateInitialRoutes], which
   /// defaults to [defaultGenerateInitialRoutes].
+  ///
+  /// Changing the [initialRoute] will have no effect, as it only controls the
+  /// _initial_ route. To change the route while the application is running, use
+  /// the static functions on this class, such as [push] or [replace].
   final String? initialRoute;
 
   /// Called to generate a route for a given [RouteSettings].