Update Upgrade documentation and guides

[fedekunze]

Summary of Bug

The current upgrade guides and docs are not helpful for projects as:

• docs are scattered across different files (In-Place Store Migrations, Upgrading Modules, Migrations Section, Upgrade Module spec, Cosmovisor)
• it doesn't handle the cases of planned vs unplanned upgrades
• it doesn't handle the cases of running cosmovisor vs not using cosmovisor
• it doesn't handle the cases of automated vs manual upgrades
• it doesn't contain documentation in case of automated upgrade failure
• it doesn't have any explanation of the migrate command. What is it used for? Is it outdated?
• it doesn't have any reference to the pre-upgrade command. What is it used for?
• it doesn't contain how-to guides for adding new modules vs updating existing modules
• it doesn't handle cases of adding new params vs changing existing params
• it doesn't contain documentation or a reference on what to do with IBC connections after upgrades. This is located in the IBC docs but not referenced in the SDK

Version

master

Proposal

Rewrite the current Migrations section on the SDK docs and create a go-to Upgrade guide that covers everything

cc: @marbar3778 @alexanderbez

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[alexanderbez]

Totally agree with this. Docs for live on-chain upgrades are too scattered, and sometimes otherwise completely lacking.

[fedekunze]

started working on it here: https://hackmd.io/@fedekunze/cosmos-upgrade-guide

[alexanderbez]

@fedekunze we need docs in the SDK that are app agnostic. Docs that describe the general flow, steps and procedures, and how to write upgrade handlers for various use-cases.

[fedekunze]

Agree, we are writing them using evmosd as a reference but happy to update the examples

[julienrbrt]

docs are scattered across different files (In-Place Store Migrations, Upgrading Modules, Migrations Section, Upgrade Module spec, Cosmovisor)

Few notes on the that, as I just skimmed the migration docs:

Killed the migrations section for that usage here #15575. It will be about the SDK itself.
A module dev may be a different person than a chain dev, so having different documentation makes sense to me.
Cosmovisor docs separated from the rest makes sense as well, as it is documentation for the tool.
The new section under building-apps (ex migration section) should probably refer to the core/upgrade section and possibly completely replace it and be enhanced with your guide.