docs: re-arrange and clarify migration docs (backport #15575) (#15584)

Co-authored-by: Julien Robert <julien@rbrt.fr>
cosmos · Mar 28, 2023 · 418ca33 · 418ca33
1 parent 0af178d
commit 418ca33
Show file tree

Hide file tree

Showing 8 changed files with 36 additions and 14 deletions.
diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md
@@ -111,7 +111,7 @@ ways in stable releases and `main` branch.
 
 ### Migrations
 
-To smoothen the update to the latest stable release, the SDK includes a set of CLI commands for managing migrations between SDK versions, under the `migrate` subcommand. Only migration scripts between stable releases are included. For the current major release, and later, migrations are supported.
+See the SDK's policy on migrations [here](https://docs.cosmos.network/main/migrations/intro).
 
 ### What qualifies as a Stable Release Update (SRU)
 

diff --git a/docs/docs/migrations/01-pre-upgrade.md → docs/docs/building-apps/03-app-upgrade.md b/docs/docs/migrations/01-pre-upgrade.md → docs/docs/building-apps/03-app-upgrade.md
@@ -2,7 +2,17 @@
 sidebar_position: 1
 ---
 
-# Pre-Upgrade Handling
+# Application upgrade
+
+:::note
+This document describes how to upgrade your application. If you are looking specifically for the changes to perform between SDK versions, see the [SDK migrations documentation](https://docs.cosmos.network/main/migrations/intro).
+:::
+
+:::warning
+This section is currently incomplete. Track the progress of this document [here](https://github.com/cosmos/cosmos-sdk/issues/11504).
+:::
+
+## Pre-Upgrade Handling
 
 Cosmovisor supports custom pre-upgrade handling. Use pre-upgrade handling when you need to implement application config changes that are required in the newer version before you perform the upgrade.
 

diff --git a/docs/docs/migrations/00-intro.md b/docs/docs/migrations/00-intro.md
diff --git a/docs/docs/migrations/01-intro.md b/docs/docs/migrations/01-intro.md
@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# SDK Migrations
+
+To smoothen the update to the latest stable release, the SDK includes a CLI command for hard-fork migrations (under the `<appd> genesis migrate` subcommand). 
+Additionally, the SDK includes in-place migrations for its core modules. These in-place migrations are useful to migrate between major releases.
+
+* Hard-fork migrations are supported from the last major release to the current one.
+* In-place module migrations are supported from the last two major releases to the current one.
+
+Migration from a version older than the last two major releases is not supported.
+
+When migrating from a previous version, refer to the [`UPGRADING.md`](./02-upgrading.md) and the `CHANGELOG.md` of the version you are migrating to.
diff --git a/docs/docs/migrations/_category_.json b/docs/docs/migrations/_category_.json
@@ -1,5 +1,5 @@
 {
-    "label": "Migrations",
+    "label": "SDK Migrations",
     "position": 6,
     "link": null
 }
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -400,6 +400,10 @@ const config = {
             from: ["/main/run-node/cosmovisor"],
             to: "/main/tooling/cosmovisor",
           },
+          {
+            from: ["/main/migrations/pre-upgrade"],
+            to: "/main/building-apps/app-upgrade",
+          },
         ],
       },
     ],

diff --git a/docs/post.sh b/docs/post.sh
@@ -6,4 +6,5 @@ rm -rf docs/tooling/02-depinject.md
 rm -rf docs/run-node/04-rosetta.md
 rm -rf docs/architecture
 rm -rf docs/spec
+rm -rf docs/migrations/02-upgrading.md
 rm -rf versioned_docs versioned_sidebars versions.json
diff --git a/docs/pre.sh b/docs/pre.sh
@@ -31,3 +31,6 @@ cp -r ./architecture ./docs
 
 ## Add spec documentation
 cp -r ./spec ./docs
+
+## Add SDK migration documentation
+cp -r ../UPGRADING.md ./docs/migrations/02-upgrading.md