diff --git a/doc/flame/flame.md b/doc/flame/flame.md
index 2db4d0b6905..9d5ac4fffb1 100644
--- a/doc/flame/flame.md
+++ b/doc/flame/flame.md
@@ -1,6 +1,7 @@
 # Flame
 
 - [Getting Started](../README.md)
+- [Migration Guides](migration.md)
 - [Game Widget](game_widget.md)
 - [The game class](game.md)
 - [Assets Structure](structure.md)
@@ -20,6 +21,7 @@
 :hidden:
 
 Getting Started      <../README.md>
+Migration Guides     <migration.md>
 Game Widget          <game_widget.md>
 The game class       <game.md>
 Assets Structure     <structure.md>
diff --git a/doc/flame/migration.md b/doc/flame/migration.md
new file mode 100644
index 00000000000..e0047302499
--- /dev/null
+++ b/doc/flame/migration.md
@@ -0,0 +1,27 @@
+# Migration Guides
+
+This section describes the breaking changes that you need to be aware of when upgrading between
+major versions of Flame, together with the steps required to migrate your code.
+
+
+## Migrating from v1.38.0 to v2.0.0
+
+
+### `GameWidget.controlled` renamed to `GameWidget.managed`
+
+The `GameWidget.controlled` constructor has been renamed to `GameWidget.managed`. The behavior is
+unchanged; only the name is different.
+
+Replace every usage of `GameWidget.controlled` with `GameWidget.managed`:
+
+```dart
+// Before
+GameWidget.controlled(
+  gameFactory: MyGame.new,
+);
+
+// After
+GameWidget.managed(
+  gameFactory: MyGame.new,
+);
+```