Skip to content

Commit

Permalink
docs: add chain upgrade guide v0.43 (cosmos#9567)
Browse files Browse the repository at this point in the history
## Description

<!-- Add a description of the changes that this PR introduces and the files that
are the most critical to review. -->

This pull request adds a chain upgrade guide and example for v0.43. This pull request also removes migration documentation specific to v0.42 and adds links to v0.42 documentation when referencing genesis migrations.

---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [x] included the correct `docs:` prefix in the PR title
- [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [x] provided a link to the relevant issue or specification - n/a
- [x] followed the [documentation writing guidelines](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOC_WRITING_GUIDELINES.md)
- [x] reviewed "Files changed" and left comments if necessary
- [x] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [x] confirmed the correct `docs:` prefix in the PR title
- [x] confirmed all author checklist items have been addressed 
- [ ] confirmed that this PR only changes documentation
- [ ] reviewed content for consistency
- [ ] reviewed content for thoroughness
- [ ] reviewed content for spelling and grammar
- [ ] tested instructions (if applicable)
  • Loading branch information
ryanchristo authored Jul 19, 2021
1 parent 57d21fa commit 6098d7e
Show file tree
Hide file tree
Showing 8 changed files with 334 additions and 507 deletions.
128 changes: 78 additions & 50 deletions cosmovisor/README.md

Large diffs are not rendered by default.

12 changes: 6 additions & 6 deletions docs/building-modules/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,26 @@
order: 13
-->

# In-Place Store Migrations
# Upgrading Modules

In-place store migrations allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis}
[In-Place Store Migrations](../core/upgrade.html) allow your modules to upgrade to new versions that include breaking changes. This document outlines how to build modules to take advantage of this functionality. {synopsis}

## Prerequisite Readings

- [In-Place Store Migration](../core/upgrade.md) {prereq}

## Consensus Version

Successful upgrades of existing modules require your `AppModule` to implement the function `ConsensusVersion() uint64`.
Successful upgrades of existing modules require each `AppModule` to implement the function `ConsensusVersion() uint64`.

- The versions must be hard-coded by the module developer.
- The initial version **must** be set to 1.

Consensus versions serve as state-breaking versions of app modules and are incremented when the module is upgraded.
Consensus versions serve as state-breaking versions of app modules and must be incremented when the module introduces breaking changes.

## Registering Migrations

To register the functionality that takes place during a module upgrade, you must register which migrations we want to take place.
To register the functionality that takes place during a module upgrade, you must register which migrations you want to take place.

Migration registration takes place in the `Configurator` using the `RegisterMigration` method. The `AppModule` reference to the configurator is in the `RegisterServices` method.

Expand Down Expand Up @@ -54,4 +54,4 @@ func (m Migrator) Migrate1to2(ctx sdk.Context) error {
}
```

To see example code of changes that were implemented in a migration of balance keys, check out the [func migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/36f68eb9e041e20a5bb47e216ac5eb8b91f95471/x/bank/legacy/v043/store.go#L41-L62) code. For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../architecture/adr-028-public-key-addresses.md).
To see example code of changes that were implemented in a migration of balance keys, check out [migrateBalanceKeys](https://github.com/cosmos/cosmos-sdk/blob/36f68eb9e041e20a5bb47e216ac5eb8b91f95471/x/bank/legacy/v043/store.go#L41-L62). For context, this code introduced migrations of the bank store that updated addresses to be prefixed by their length in bytes as outlined in [ADR-028](../architecture/adr-028-public-key-addresses.md).
16 changes: 8 additions & 8 deletions docs/core/upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ order: 15
Read and understand all of the in-place store migration documentation before you run a migration on a live chain.
:::

Upgrade your app modules smoothly with custom in-place migration logic. {synopsis}
Upgrade your app modules smoothly with custom in-place store migration logic. {synopsis}

The Cosmos SDK uses two methods to perform upgrades.

- Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See the [Chain Upgrade Guide](../migrations/chain-upgrade-guide-040.md#upgrade-procedure).
- Exporting the entire application state to a JSON file using the `export` CLI command, making changes, and then starting a new binary with the changed JSON file as the genesis file. See [Chain Upgrade Guide to v0.42](/v0.42/migrations/chain-upgrade-guide-040.html).

- Version v0.43 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Migration Upgrade Guide](../building-modules/upgrade.md) guide to set up your application modules to take advantage of in-place upgrades.
- Version v0.43 and later can perform upgrades in place to significantly decrease the upgrade time for chains with a larger state. Use the [Module Upgrade Guide](../building-modules/upgrade.md) to set up your application modules to take advantage of in-place upgrades.

This document provides steps to use the In-Place Store Migrations upgrade method.

Expand Down Expand Up @@ -48,21 +48,21 @@ The version map is a mapping of module names to consensus versions. The map is p

Upgrades use an `UpgradeHandler` to facilitate migrations. The `UpgradeHandler` functions implemented by the app developer must conform to the following function signature. These functions retrieve the `VersionMap` from x/upgrade's state and return the new `VersionMap` to be stored in x/upgrade after the upgrade. The diff between the two `VersionMap`s determines which modules need upgrading.

```golang
```go
type UpgradeHandler func(ctx sdk.Context, plan Plan, fromVM VersionMap) (VersionMap, error)
```

Inside these functions, you must perform any upgrade logic to include in the provided `plan`. All upgrade handler functions must end with the following line of code:

```golang
```go
return app.mm.RunMigrations(ctx, cfg, fromVM)
```

## Running Migrations

Migrations are run inside of an `UpgradeHandler` using `app.mm.RunMigrations(ctx, cfg, vm)`. The `UpgradeHandler` functions describe the functionality to occur during an upgrade. The `RunMigration` function loops through the `VersionMap` argument and runs the migration scripts for all versions that are less than the versions of the new binary app module. After the migrations are finished, a new `VersionMap` is returned to persist the upgraded module versions to state.

```golang
```go
cfg := module.NewConfigurator(...)
app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) {

Expand All @@ -76,7 +76,7 @@ app.UpgradeKeeper.SetUpgradeHandler("my-plan", func(ctx sdk.Context, plan upgrad
})
```

To learn more about configuring migration scripts for your modules, see the [Migration Upgrade Guide](../building-modules/upgrade.md).
To learn more about configuring migration scripts for your modules, see the [Module Upgrade Guide](../building-modules/upgrade.md).

## Adding New Modules During Upgrades

Expand All @@ -86,7 +86,7 @@ You can introduce entirely new modules to the application during an upgrade. New

All chains preparing to run in-place store migrations will need to manually add store upgrades for new modules and then configure the store loader to apply those upgrades. This ensures that the new module's stores are added to the multistore before the migrations begin.

```golang
```go
upgradeInfo, err := app.UpgradeKeeper.ReadUpgradeInfoFromDisk()
if err != nil {
panic(err)
Expand Down
Loading

0 comments on commit 6098d7e

Please sign in to comment.