diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..863c19e
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,23 @@
+# Upgrading from v1 to v2
+
+LmcAdmin v2 is a major version upgrade with many breaking changes that prevent
+straightforward upgrading.
+
+### Namespace change
+
+The namespace has been changed from LmcAdmin to Lmc\Admin.
+
+Please review your code to replace references to the `LmcAdmin` namespace
+by the `Lmc\Admin` namespace.
+
+### Default layout template name
+
+The default layout template has been changed from `layout/admin` to `layout/lmcadmin`.
+
+The `index` action of the `AdminController` now returns a View Model with its template set to
+`'lmc-admin/admin/index'`. To use your customer view template, you need to add a View Manager
+template map entry for `'lmc-admin/admin/index'` that points to your custom view.
+
+### Configuration key
+
+The configuration key for LmcAdmin was changed from `lmcadmin` to `lmc_admin`. 
diff --git a/docs/docs/Upgrading/to-v2.md b/docs/docs/Upgrading/to-v2.md
index 67c4c2c..6544ebb 100644
--- a/docs/docs/Upgrading/to-v2.md
+++ b/docs/docs/Upgrading/to-v2.md
@@ -15,7 +15,11 @@ by the `Lmc\Admin` namespace.
 
 ### Default layout template name
 
-The default layout template has been changed from `layout/admin` to `layout/lmcadmin`.
+The default layout template has been changed from `layout/admin` to `layout/lmcadmin`
+
+The `index` action of the `AdminController` now returns a View Model with its template set to
+`'lmc-admin/admin/index'`. To use your customer view template, you need to add a View Manager
+template map entry for `'lmc-admin/admin/index'` that points to your custom view.
 
 ### Configuration key
 
diff --git a/docs/versioned_docs/version-2.0/Upgrading/to-v2.md b/docs/versioned_docs/version-2.0/Upgrading/to-v2.md
index 67c4c2c..2eed26b 100644
--- a/docs/versioned_docs/version-2.0/Upgrading/to-v2.md
+++ b/docs/versioned_docs/version-2.0/Upgrading/to-v2.md
@@ -17,6 +17,10 @@ by the `Lmc\Admin` namespace.
 
 The default layout template has been changed from `layout/admin` to `layout/lmcadmin`.
 
+The `index` action of the `AdminController` now returns a View Model with its template set to
+`'lmc-admin/admin/index'`. To use your customer view template, you need to add a View Manager
+template map entry for `'lmc-admin/admin/index'` that points to your custom view.
+
 ### Configuration key
 
 The configuration key for LmcAdmin was changed from `lmcadmin` to `lmc_admin`.