From 71ef8bd3ff207fd51c2ca18d5a8c7140476780c7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Ollivier?= <clement.o2p@gmail.com>
Date: Thu, 22 Sep 2022 17:24:32 +0200
Subject: [PATCH] docs(migration): restructure upgrade guide (#7730)

---
 .../10.upgrade-guide/0.migration.md           | 28 ---------
 docs/content/1.getting-started/10.upgrade.md  | 59 +++++++++++++++++++
 .../4.going-further/11.edge-channel.md}       |  0
 docs/static/_redirects                        |  5 +-
 4 files changed, 62 insertions(+), 30 deletions(-)
 delete mode 100644 docs/content/1.getting-started/10.upgrade-guide/0.migration.md
 create mode 100644 docs/content/1.getting-started/10.upgrade.md
 rename docs/content/{1.getting-started/10.upgrade-guide/1.edge-channel.md => 2.guide/4.going-further/11.edge-channel.md} (100%)

diff --git a/docs/content/1.getting-started/10.upgrade-guide/0.migration.md b/docs/content/1.getting-started/10.upgrade-guide/0.migration.md
deleted file mode 100644
index fc248fdb3e7..00000000000
--- a/docs/content/1.getting-started/10.upgrade-guide/0.migration.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Migration Guide
-
-Already have a Nuxt project to migrate? These migration guides are for users wanting to upgrade their Nuxt application to Nuxt 3 or take the first step in that direction with Nuxt Bridge.
-
-- [**From Nuxt 2 to Nuxt 3**](/migration/overview)
-- [From Nuxt 2 to Nuxt Bridge](/bridge/overview)
-
-## Feature Comparison
-
-In the table below, there is a quick comparison between 3 versions of Nuxt:
-
-Feature / Version        | Nuxt 2          | Nuxt Bridge      | Nuxt 3
--------------------------|-----------------|------------------|---------
-Vue                      | 2               | 2                | 3
-Stability                | 😊 Stable      | 😌 Semi-stable   | 😬 Unstable
-Performance              | 🏎 Fast        | ✈️ Faster        | 🚀 Fastest
-Nitro Engine             | ❌             | ✅               | ✅
-ESM support              | 🌙 Partial     | 👍 Better        | ✅
-TypeScript               | ☑️ Opt-in      | 🚧 Partial       | ✅
-Composition API          | ❌             | 🚧 Partial       | ✅
-Options API              | ✅             | ✅               | ✅
-Components Auto Import   | ✅             | ✅               | ✅
-`<script setup>` syntax  | ❌             | 🚧 Partial       | ✅
-Auto Imports             | ❌             | ✅               | ✅
-Webpack                  | 4              | 4                | 5
-Vite                     | ⚠️ Partial     | 🚧 Partial       | ✅
-Nuxi CLI                 | ❌ Old         | ✅ nuxi          | ✅ nuxi
-Static sites             | ✅             | ✅               | 🚧 Experimental
diff --git a/docs/content/1.getting-started/10.upgrade.md b/docs/content/1.getting-started/10.upgrade.md
new file mode 100644
index 00000000000..37d5dd875ec
--- /dev/null
+++ b/docs/content/1.getting-started/10.upgrade.md
@@ -0,0 +1,59 @@
+# Upgrade Guide
+
+Have a Nuxt 2 project to migrate? Use these guides to upgrade your Nuxt applications to Nuxt 3 or take the first step in that direction with Nuxt Bridge.
+
+If you are already using Nuxt 3 and want to upgrade to the latest release or test new features before their release, head over to the [Upgrading Nuxt 3](#upgrading-nuxt-3) section.
+
+## Feature Comparison
+
+In the table below, there is a quick comparison between 3 versions of Nuxt:
+
+Feature / Version        | Nuxt 2          | Nuxt Bridge      | Nuxt 3
+-------------------------|-----------------|------------------|---------
+Vue                      | 2               | 2                | 3
+Stability                | 😊 Stable      | 😌 Semi-stable    | Release candidate
+Performance              | 🏎 Fast        | ✈️ Faster          | 🚀 Fastest
+Nitro Engine             | ❌             | ✅                | ✅
+ESM support              | 🌙 Partial     | 👍 Better         | ✅
+TypeScript               | ☑️ Opt-in       | 🚧 Partial        | ✅
+Composition API          | ❌             | 🚧 Partial        | ✅
+Options API              | ✅             | ✅                | ✅
+Components Auto Import   | ✅             | ✅                | ✅
+`<script setup>` syntax  | ❌             | 🚧 Partial        | ✅
+Auto Imports             | ❌             | ✅                | ✅
+Webpack                  | 4              | 4                 | 5
+Vite                     | ⚠️ Partial      | 🚧 Partial        | ✅
+Nuxi CLI                 | ❌ Old         | ✅ nuxi           | ✅ nuxi
+Static sites             | ✅             | ✅                | ✅
+
+## Nuxt 2 to Nuxt 3
+
+The migration guide provides a step-by-step comparison of Nuxt 2 features to Nuxt 3 features and guidance to adapt your current application.
+
+::alert{type=info icon=👉}
+[**Migrate from From Nuxt 2 to Nuxt 3**](/migration/overview)
+::
+
+## Nuxt 2 to Nuxt Bridge
+
+If you prefer to progressively migrate your Nuxt 2 application to Nuxt 3, you can use Nuxt Bridge. Nuxt Bridge is a compatibility layer that allows you to use Nuxt 3 features in Nuxt 2 with an opt-in mechanism.
+
+::alert{type=info icon=👉}
+[**Migrate from Nuxt 2 to Nuxt Bridge**](/bridge/overview)
+::
+
+## Upgrading Nuxt 3
+
+### Latest release
+
+To upgrade Nuxt 3 to the latest release, use the `nuxi upgrade` command.
+
+```bash
+npx nuxi upgrade
+```
+
+### Edge release channel
+
+::alert{type=info icon=👉}
+To use the latest Nuxt 3 build and test features before their release, read the [edge release channel](/guide/going-further/edge-channel) guide.
+::
diff --git a/docs/content/1.getting-started/10.upgrade-guide/1.edge-channel.md b/docs/content/2.guide/4.going-further/11.edge-channel.md
similarity index 100%
rename from docs/content/1.getting-started/10.upgrade-guide/1.edge-channel.md
rename to docs/content/2.guide/4.going-further/11.edge-channel.md
diff --git a/docs/static/_redirects b/docs/static/_redirects
index 27a1ba68501..c6b8c29468f 100644
--- a/docs/static/_redirects
+++ b/docs/static/_redirects
@@ -40,8 +40,9 @@
 /guide/features/state-management  /getting-started/state-management 302!
 /guide/features/error-handling    /getting-started/error-handling 302!
 /guide/going-further/testing      /getting-started/testing 302!
-/getting-started/migration        /getting-started/upgrade-guide/migration 302!
-/guide/going-further/edge-channel /getting-started/upgrade-guide/edge-channel 302!
+/getting-started/migration        /getting-started/upgrade-guide/migration 302
+/getting-started/upgrade-guide/migration /getting-started/upgrade 302!
+/getting-started/upgrade-guide/edge-channel /guide/going-further/edge-channel 302!
 /guide/features/modules           /guide/concepts/modules 302!
 /guide/features/server-routes     /guide/directory-structure/server 302!
 /guide/going-further/esm          /guide/concepts/esm 302!