documentation for in-place migrations with x/upgrade module

[technicallyty]

Description

Adds documentation for both module and application developers who want to utilize the in-place store migration functionality with x/upgrade.

closes: #8940

---

Before we can merge this PR, please make sure that all the following items have been
checked off. If any of the checklist items are not applicable, please leave them but
write a little note why.

• Targeted PR against correct branch (see CONTRIBUTING.md)
• Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
• Code follows the module structure standards.
• Wrote unit and integration tests
• Updated relevant documentation (docs/) or specification (x/<module>/spec/)
• Added relevant godoc comments.
• Added a relevant changelog entry to the Unreleased section in CHANGELOG.md
• Re-reviewed Files changed in the Github PR explorer
• Review Codecov Report in the comment section below once CI passes

[amaury1093]

Read through it, it looks good! I added some improvement proposals

[amaury1093]

Blocking this PR for now. We might need bigger warnings on this docs, like "be careful what you're doing here".

Also, would like to add a small section about #8988 (comment). If you have context on that @technicallyty, feel free to take a stab at it. happy to discuss this with you more in details during a call.

We might also need a paragraph on InitGenesis stuff #8989 (comment), but that's still WIP

[technicallyty]

Yeah that makes sense. There should be clear cut ways for an app dev to smoothly introduce new modules w/ genesis etc

[zmanian]

Once a chain is upgraded using an in place store migration, how does a new node sync?

During the in place store migration there is no genesis file generates for a new node to sync from.

State sync can be used to instant sync to height.

This question should be addressed in this document.

[amaury1093]

Once a chain is upgraded using an in place store migration, how does a new node sync?

If the upgrade looks like binary_1 -> height N -> binary_2 then the full node must use those same binaries at those same heights, e.g. with a cosmovisor swap at N. Cosmovisor handles downloading binaries on the fly, so in the cosmovisor use-case there's no user intervention during the sync (or shouldn't be, I'm not sure anyone's tested in-place migrations with cosmovisor, see #9069).

This question should be addressed in this document.

Makes sense. @technicallyty would you be able to add a section on full node sync?

[technicallyty]

Once a chain is upgraded using an in place store migration, how does a new node sync?

If the upgrade looks like binary_1 -> height N -> binary_2 then the full node must use those same binaries at those same heights, e.g. with a cosmovisor swap at N. Cosmovisor handles downloading binaries on the fly, so in the cosmovisor use-case there's no user intervention during the sync (or shouldn't be, I'm not sure anyone's tested in-place migrations with cosmovisor, see #9069).

This question should be addressed in this document.

Makes sense. @technicallyty would you be able to add a section on full node sync?

added sync section. Not sure how specific I needed to get here, so let me know if im missing any important notes.

[zmanian]

Sync section looks good to me

[amaury1093]

lgtm 👍

[amaury1093]

I remember reading a sentence saying something like "this document describes the 2nd method", imo it's still useful to add it here

[technicallyty]

specified method

[technicallyty]

updated the section about fromVM == 0 to reflect this PR

[barriebyron]

let's describe the purpose of the doc instead of "specified " or "mentioned above"

looks good!

[tac0turtle]

Thank you for this, it answered some open questions of mine