Documentation example of data migration

[JustAnotherArchivist]

I'm confused about the example for data migration during code updates. The runMigration example function asserts that this is an upgrade from version 0 to version 1. Shouldn't this be from version 1 to version 2? Or am I completely misunderstanding how migrations work?

Furthermore, I think that the onCodeVersionChanged callback (runMigration in the example) is called on each code version change, right? If so, shouldn't the function check the versions with an if and return if it's not the expected value rather than using assert? The relevant code calling the callback doesn't catch AssertionError, so I'd expect that code to crash when the node running it isn't on version 1. Also, you'd have to remove (or update) the callback before doing any further changes. This could be a bit clearer in the documentation.

[bakwc]

Inital version is 0, so the first time migration will be from 0 to 1. Assert is just an example (there is only one possible migration in example, from 0 to 1), in more complex cases you should handle all possible migrations yourself, for each version.

[bakwc]

I'll write some documentation, thanks for report. BTW, you could add some comments / write documentation, I'll be glad to accept your PR.

[JustAnotherArchivist]

Inital version is 0, so the first time migration will be from 0 to 1.

Right, but as I understand it, the example builds on the previous example where version 1 adds pop. Version 1 still uses the simple data storage (where each dict entry just contains the value); the data structure then changes between versions 1 and 2. Or am I misreading the code?

BTW, you could add some comments / write documentation, I'll be glad to accept your PR.

Unfortunately, I don't think it's possible to do this for the GitHub wiki easily. Although the wiki is a git repository, it isn't possible to create PRs for it as far as I know.

By the way, impressive responsiveness! 👍