Update docs to explain state migration side-effects on accessing stored values

[nvdtf]

Issue to be solved

Ref onflow/flow-nft#126 (comment)

In the above discussion we observed there will be some side effects with accessing stored values after migration.

For example, an NFT collection that can be accessed with:

account.capabilities.borrow<&{NonFungibleToken.Collection}>

Should now be written as:

account.capabilities.borrow<&{
        NonFungibleToken.CollectionPublic,
        ExampleNFT.ExampleNFTCollectionPublic,
        ViewResolver.ResolverCollection
    }>

This issue is not asking for the above to be solved, but to explain it in a special paragraph/section in the docs as we think it might raise some questions during the migration process for developers.

Suggested Solution

Add a special section or paragraph in the migration docs about how to solve common issues with accessing migrated values.

[SupunS]

@nvdtf Can you please check if this still the case? I tried with the CLI v1.15.0-cadence-v1.0.0-preview.13 (there are even newer versions, so maybe try with the latest), and I could borrow the old value with account.capabilities.borrow<&{NonFungibleToken.Collection}>, just like the old way, even after the migration.

[SupunS]

@onflow/cadence Being able to borrow with &{NonFungibleToken.Collection} was a bit of a surprise, because the old value was linked as:

self.account.link<&ExampleNFT.Collection{NonFungibleToken.CollectionPublic, ExampleNFT.ExampleNFTCollectionPublic, MetadataViews.ResolverCollection}>(
    self.CollectionPublicPath,
    target: self.CollectionStoragePath
)

But thinking about it more, It seems correct, because with the entitlement migration &ExampleNFT.Collection{NonFungibleToken.CollectionPublic, ExampleNFT.ExampleNFTCollectionPublic, MetadataViews.ResolverCollection} becomes just &ExampleNFT.Collection, and should be able to borrow with any interface it implements (i.e: with any subtype of ExampleNFT.Collection)?

[turbolent]

@SupunS Thanks for looking into this!

Being able to borrow with &{NonFungibleToken.Collection} makes sense and seems correct (though a little bit surprising at first, but then not at all), and I guess that applies to both values migrated from pre-1.0 and values created in 1.0?

[SupunS]

I guess that applies to both values migrated from pre-1.0 and values created in 1.0?

yes