docs: re-arrange and clarify migration docs

RELEASE_PROCESS.md

@@ -120,7 +120,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)
 

UPGRADING.md

@@ -66,16 +66,16 @@ This is no longer the case, the assertion has been loosened to only require modu
 
 The following modules `NewKeeper` function now take a `KVStoreService` instead of a `StoreKey`:
 
-- `x/auth`
-- `x/consensus`
+* `x/auth`
+* `x/consensus`
 
 When not using depinject, the `runtime.NewKVStoreService` method can be used to create a `KVStoreService` from a `StoreKey`:
 
 ```diff
-- app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper(appCodec, keys[consensusparamtypes.StoreKey], authtypes.NewModuleAddress(govtypes.ModuleName).String())
-+ app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper(
+app.ConsensusParamsKeeper = consensusparamkeeper.NewKeeper(
   appCodec,
-  runtime.NewKVStoreService(keys[consensusparamtypes.StoreKey]),
++ keys[consensusparamtypes.StoreKey]
++ runtime.NewKVStoreService(keys[consensusparamtypes.StoreKey]),
   authtypes.NewModuleAddress(govtypes.ModuleName).String(),
 )
 ```

docs/.gitignore

@@ -19,6 +19,7 @@ docs/docs/tooling/02-depinject.md
 docs/docs/tooling/03-confix.md
 docs/docs/tooling/04-hubl.md
 docs/run-node/04-rosetta.md
+docs/migrations/02-upgrading.md
 
 # Misc
 .DS_Store

docs/docs/migrations/01-pre-upgrade.md → docs/docs/building-apps/03-migrations.md

@@ -2,7 +2,13 @@
 sidebar_position: 1
 ---
 
-# Pre-Upgrade Handling
+# Migrations
+
+:::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)
+:::
+
+## 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.
 

docs/docs/migrations/00-intro.md

@@ -2,10 +2,14 @@
 sidebar_position: 1
 ---
 
-# Introduction to Migrations
+# SDK Migrations
 
-This document contains all the migration guides to update your app and modules to the current Cosmos SDK.
+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.
 
-1. Chain Upgrade Guide to v0.47:
-   * See [UPGRADING.md](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/UPGRADING.md) for breaking changes and deprecations upgrade instructions.
-   * See [Release Notes](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/RELEASE_NOTES.md) and [changelog](https://github.com/cosmos/cosmos-sdk/blob/v0.47.0-rc1/CHANGELOG.md) for the exhaustive list of API and State Machine breaking changes.
+* Hard-fork migrations are supported from the last major release to the current one.
+* In-place module migrations are supported from the two last major releases to the current one.
+
+Migration from a version older than the two last major releases is not supported.
+
+When migrating from a previous version, refer to the `UPGRADING.md` and the `CHANGELOG` of the version you are migrating to.

docs/docs/migrations/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "Migrations",
+    "label": "SDK Migrations",
     "position": 6,
     "link": null
 }

docs/post.sh

@@ -9,4 +9,5 @@ rm -rf docs/run-node/04-rosetta.md
 rm -rf docs/architecture
 rm -rf docs/spec
 rm -rf docs/rfc
+rm -rf docs/migrations/02-upgrading.md
 rm -rf versioned_docs versioned_sidebars versions.json

docs/pre.sh

@@ -33,4 +33,7 @@ cp -r ./architecture ./docs
 cp -r ./spec ./docs
 
 ## Add rfc documentation
-cp -r ./rfc ./docs
+cp -r ./rfc ./docs
+
+## Add SDK migration documentation
+cp -r ../UPGRADING.md ./docs/migrations/02-upgrading.md