docs: improve RegisterMigration docs (#11225)

## Description

Small documentation improvement. By reading the function header I thought `forVersion` will mean the `destination` and made a bug. So, I propose to use more clear function argument name: `forVersion` -> `fromVersion`. 

---

### 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...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] 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...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
This commit is contained in:
Robert Zaremba 2022-02-18 13:42:47 +01:00 committed by GitHub
parent ea67659950
commit fcd02d06e2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 12 additions and 12 deletions

View File

@ -106,7 +106,7 @@ func TestRunMigrations(t *testing.T) {
testCases := []struct {
name string
moduleName string
forVersion uint64
fromVersion uint64
expRegErr bool // errors while registering migration
expRegErrMsg string
expRunErr bool // errors while running migration
@ -134,7 +134,7 @@ func TestRunMigrations(t *testing.T) {
false, "", false, "", 1,
},
{
"cannot register migration handler for same module & forVersion",
"cannot register migration handler for same module & fromVersion",
"bank", 1,
true, "another migration for module bank and version 1 already exists: internal logic error", false, "", 0,
},
@ -151,8 +151,8 @@ func TestRunMigrations(t *testing.T) {
called := 0
if tc.moduleName != "" {
// Register migration for module from version `forVersion` to `forVersion+1`.
err = app.configurator.RegisterMigration(tc.moduleName, tc.forVersion, func(sdk.Context) error {
// Register migration for module from version `fromVersion` to `fromVersion+1`.
err = app.configurator.RegisterMigration(tc.moduleName, tc.fromVersion, func(sdk.Context) error {
called++
return nil

View File

@ -26,14 +26,14 @@ type Configurator interface {
// RegisterMigration registers an in-place store migration for a module. The
// handler is a migration script to perform in-place migrations from version
// `forVersion` to version `forVersion+1`.
// `fromVersion` to version `fromVersion+1`.
//
// EACH TIME a module's ConsensusVersion increments, a new migration MUST
// be registered using this function. If a migration handler is missing for
// a particular function, the upgrade logic (see RunMigrations function)
// will panic. If the ConsensusVersion bump does not introduce any store
// changes, then a no-op function must be registered here.
RegisterMigration(moduleName string, forVersion uint64, handler MigrationHandler) error
RegisterMigration(moduleName string, fromVersion uint64, handler MigrationHandler) error
}
type configurator struct {
@ -41,7 +41,7 @@ type configurator struct {
msgServer grpc.Server
queryServer grpc.Server
// migrations is a map of moduleName -> forVersion -> migration script handler
// migrations is a map of moduleName -> fromVersion -> migration script handler
migrations map[string]map[uint64]MigrationHandler
}
@ -68,8 +68,8 @@ func (c configurator) QueryServer() grpc.Server {
}
// RegisterMigration implements the Configurator.RegisterMigration method
func (c configurator) RegisterMigration(moduleName string, forVersion uint64, handler MigrationHandler) error {
if forVersion == 0 {
func (c configurator) RegisterMigration(moduleName string, fromVersion uint64, handler MigrationHandler) error {
if fromVersion == 0 {
return sdkerrors.Wrap(sdkerrors.ErrInvalidVersion, "module migration versions should start at 1")
}
@ -77,11 +77,11 @@ func (c configurator) RegisterMigration(moduleName string, forVersion uint64, ha
c.migrations[moduleName] = map[uint64]MigrationHandler{}
}
if c.migrations[moduleName][forVersion] != nil {
return sdkerrors.Wrapf(sdkerrors.ErrLogic, "another migration for module %s and version %d already exists", moduleName, forVersion)
if c.migrations[moduleName][fromVersion] != nil {
return sdkerrors.Wrapf(sdkerrors.ErrLogic, "another migration for module %s and version %d already exists", moduleName, fromVersion)
}
c.migrations[moduleName][forVersion] = handler
c.migrations[moduleName][fromVersion] = handler
return nil
}