Add MIGRATING.md

[maurolacy]

Add breaking changes list / migration points for 0.10.x to 0.11.0.

Closes #583.

[maurolacy]

Last issue needed for 0.11 release.

[ueco-jb]

lgtm

[maurolacy]

Cool. Merging this, and cutting 0.11 next. (we need #590 / #588 first)

[ethanfrey]

This is dangerous (and I am rather sure doesn't compile).
You are writing to the same space you are reading from in an iterator.

let current = signed_int_map.range_raw(deps.storage, None, None, Order::Ascending).collect::<StdResult<Vec<_>>()?;

for (k, _) in current.iter() {
  // ?? how to delete... maybe IntKey8 uses the old format? maybe we can support OldIntKey8 that does it... would make it much easier
}

for (k, v) in current.iter() {
  let signed = i8::from_be_bytes(k);
  signed_int_map_new.save(deps.storage, signed, v)
}

This is very important issue, it would be good to have a test case for this. (Can be in 0.11.1)

[maurolacy]

Will do. Yes, I wrote that more or less as pseudo-code from memory. Will work on a proper test case / working migration example.

[maurolacy]

Please note this only affects signed int keys, which are rather rare.

[maurolacy]

Also, all the other breaking changes, including the one about removing the primary key from the multi index key spec, are non-breaking in terms of storage / data format, which is great.

[maurolacy]

You are writing to the same space you are reading from in an iterator.

Not sure this is what you mean, but notice both maps in the example have different namespace / prefix. It is assumed the new contract code will rely on the new namespace after migration.

[maurolacy]

  // ?? how to delete... maybe IntKey8 uses the old format? maybe we can support OldIntKey8 that does it... would make it much easier

Good point, I hadn't thought about that. IntKey supports the new format as well. Maybe we can change it to support the old format. Or introduce the OldIntKey wrappers for it.

The way to do it now would be

k[0] ^= 0x80;
let signed = i8::from_be_bytes(k);
signed_int_map.remove(deps.storage, I8Key::from(signed);

I think. It would be good to confirm / test this as well.

[ethanfrey]

You are writing to the same space you are reading from in an iterator.
Not sure this is what you mean, but notice both maps in the example have different namespace / prefix. It is assumed the new contract code will rely on the new namespace after migration.

Ah, that is a very good point/design.

In any case, one needs &Storage the other &mut Storage, and you cannot hold them both at the same time. (Thank you Rust)