Migration Guidance for .NET Core 1.x to .NET Core 2.0

[BillWagner]

Developers that have invested in .NET Core 1.x will need guidance for what they must do to update their libraries and applications to .NET Core 2.0.

This topic will explain those steps, following the pattern for .NET Framework migrations.

[dasMulli]

Should likely include the breaking change made by introducing implicit AssetTargetFallback values in .NET Core 2.0 / .NET Standard 2.0. See #2816 (comment)

[BillWagner]

@mairaw I'm closing this based on this doc Re-open if you don't think that covers what's needed.

[mairaw]

That topic doesn't cover. The topic I was thinking here would cover breaking changes from one version to the other, but for that to happen we'd need to coordinate with the PU team how they'd track this. We have a special process for the Framework to make that happen.

@karelz @Petermarcu any thoughts on that?

[karelz]

Breaking changes should be listed in release notes. Is that not sufficient?

[mairaw]

Not sure. For Framework, we have this fancy page where you can select origin version and target version and you get all the breaking changes between one and the other. I thought it would be a good idea to have a similar experience for Core too.

e.g. https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/runtime/4.5.1-4.6.2

[karelz]

I think it would be best to keep that information in one place - GH sounds like a good place (https://github.com/dotnet/core/tree/master/release-notes).
The docs could just link it IMO. GH is fairly flexibly in adding compat issues as we discover them.

I think the key problem is to have list of the compat problems. On one side, whenever we discover compat problems, we try to fix them. Although it often goes against each other to be compatible with 1.x vs. with Desktop. We often choose Desktop. I am not sure if there is easy way to mine that data. Maybe being reactive-ish is ok?

@leecow @richlander any thoughts?