update

docs/migrations/README.md

@@ -11,3 +11,4 @@ This folder contains all the migration guides to update your app and modules to
 1. [App and Modules Migration](./app_and_modules.md)
 1. [Chain Upgrade Guide to v0.40](./chain-upgrade-guide-040.md)
 1. [REST Endpoints Migration](./rest.md)
+1. [Keyring Migration](./keyring.md)

docs/migrations/keyring.md

@@ -1,32 +1,25 @@
+<!--
+order: 4
+-->
 # Keyring Migrate Quick Start
 
-`keyring` is mechanism of managing private/public keypair in cosmos-sdk. 
+`keyring` is mechanism for managing private/public keypair. Cosmos SDK v0.42 (Stargate) introduced some breaking changes in the keyring. Upgrading your chain from <=v0.39 to Stargate requires you to migrate your keys inside the `keyring` to the latest version. For more detailed information about the keyring, you can read [the keyring guide](../run-node/keyring.md)
 
-The more detailed information about keyring you can find here [here](../run-node/keyring.md)
+This guide describes how to perform the keyring migration process.
 
+The migration process is handled by the following CLI command:
 
-## Backends
+```bash
+Usage
+simd keys migrate <old_home_dir>
 
-The `keyring` supports the following backends:
+This command migrates key information from the legacy (db-based) Keybase to the new [keyring](https://github.com/99designs/keyring)-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. `$HOME/.gaiacli/keys/` for [Gaia](https://github.com/cosmos/gaia).
+For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated.
 
-* `os` uses the operating system's default credentials store.
-* `file` uses encrypted file-based keystore within the app's configuration directory. This keyring will request a password each time it is accessed, which may occur multiple times in a single command resulting in repeated password prompts.
-* `kwallet` uses KDE Wallet Manager as a credentials management application.
-* `pass` uses the pass command line utility to store and retrieve keys.
-* `test` stores keys insecurely to disk. It does not prompt for a password to be unlocked and it should be use only for testing purposes.
-
-
-## CLI command
-
-Usage:
-simd migrate <old_home_dir>
-
-Migrates key information from the legacy (db-based) Keybase to the new keyring-based Keyring. The legacy Keybase used to persist keys in a LevelDB database stored in a 'keys' sub-directory of the old client application's home directory **old_home_dir**, e.g. $HOME/.gaiacli/keys/. For each key material entry, the command will prompt if the key should be skipped or not. If the key is not to be skipped, the passphrase must be entered. The key will only be migrated if the passphrase is correct. Otherwise, the command will exit and migration must be repeated.
-
-You can find command implementation [here](../../client/keys/migrate.go)
-
-## Flags
-`FlagDryRun` bool flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes.
 
+The `migrate` CLI commands takes the following flags:
+- `--dry-run` boolean flag. If it's set to false, it runs migration without actually persisting any changes to the new Keybase. If it's set to true, it persists keys. This flag is useful for testing purposes: we recommend you to dry run the migration once before running it persistently.
+- `--keyring-backend` string flag. It allows you to select a backend. For more detailed information about the available backends, you can read [the keyring guide](../run-node/keyring.md).
+