[docs] Document how we plan to do multi targeting.

[rolfbjarne]

Document the plan to:

• Compile against an earlier version of our bindings.
  • [net7] Creating a cross-targeted net7.0-ios + net6.0-ios packages forces consumers to build with net7 workloads dotnet/sdk#30103
• Consume preview packages for a preview version of Xcode.
  • Figure out how to publish Xcode preview packages #18343

[rolfbjarne]

CC @pjcollins @jonathanpeppers @rmarinho @mattleibow @lewing @Redth

[jonathanpeppers]

Will we also set this when building Microsoft.iOS.dll? Roslyn emits a custom attribute that tells you to add the property in your app roject.

[rolfbjarne]

We're adding the [RequiresPreviewFeatures] attribute when building Microsoft.iOS.dll using a beta version of Xcode:

xamarin-macios/src/AssemblyInfo.cs.in

Lines 42 to 44 in 8691e43

	#if NET && !XCODE_IS_STABLE && !COREBUILD
	[assembly: RequiresPreviewFeatures("These are preview bindings for an unstable version of Xcode. Opt into preview features by adding <EnablePreviewFeatures>True</EnablePreviewFeatures> to your project file.")]
	#endif

[jonathanpeppers]

For android these were:

Microsoft.Android.Ref.33
Microsoft.Android.Ref.34
Microsoft.Android.Runtime.33.android-arm64
Microsoft.Android.Runtime.34.android-arm64

And then the same SDK pack works for all of them.

The name probably doesn't matter much, but just wanted to share what we have.

[dsplaisted]

I think you don't necessarily need to put both the .NET version and the platform version in the package ID. You could just put one of them in the package ID and use the package version to represent the other one. It's probably also fine to put both of them in the package ID if that makes things simpler.

[jonathanpeppers]

For Android, we actually need the flexibility of 33/34 on the same major .NET version. Android 35 might come out before .NET 9 is released, for example.

[jonathanpeppers]

For these, if we think that .NET 7 should use the new Xcode / bindings by default. I would consider putting net7.0-ios17.0 in the project template, but not change the default $(TargetPlatformVersion) as that might break existing projects.

[rolfbjarne]

The problem is that:

• Apple auto-updates Xcode.
• Newer Xcode might not work with older versions of our SDK.
• Putting the OS version for the TargetFramework in the template might mean that dotnet new ios will create a project that won't compile (you'll have to modify the TargetFramework to a newer OS version, or remove it completely).

That's not a good first-use experience.

Keeping backwards compatibilty has a different consequence:

• Apple auto-updates Xcode.
• A developer's project doesn't compile anymore: they update their workloads. But it still doesn't compile... (since it's using the old SDK). They'll have to add the OS version in their TargetFramework to fix it. Note that this affects most developers (if not every single one of them).

[jonathanpeppers]

Yeah, I wouldn't use this property to decide what to import. It's just a "signal" that this whole thing is preview and I have to acknowledge it.

[dsplaisted]

This is a departure from the design for platforms in the TargetFramework. Feel free to make this change if you think it's worth it, but here are some of the impacts:

• An update to the .NET SDK is more likely to break a project if it can change which version of the platform it's targeting. We want to encourage people to use the latest SDK, so we try as best we can to avoid breaking changes.
• An update to the .NET SDK can mean that a package no longer supports being consumed by older SDKs. This seems to run counter to the goal of fixing [net7] Creating a cross-targeted net7.0-ios + net6.0-ios packages forces consumers to build with net7 workloads dotnet/sdk#30103. It would mean that package authors should probably always be explicit about the target platform version.

[rolfbjarne]

An update to the .NET SDK is more likely to break a project if it can change which version of the platform it's targeting. We want to encourage people to use the latest SDK, so we try as best we can to avoid breaking changes.

That's correct for probably every other platform but ours, because of how Xcode auto-updates: earlier workload versions may not work anymore with a new Xcode, so this can happen:

• Xcode auto-updates, and a developer's project doesn't build anymore. They try updating their workloads (still fails), so they try updating .NET (still same failure) - because we keep using the same old (broken) workload. They'll have to explicitly set the target platform version in the TargetFramework (and update it again the next time Xcode is auto-updated). Note that this will effect pretty much every project/developer, so after a while most, if not all, projects actively being developed will end up with an explicit target platform version.
• dotnet new ... would create a project that doesn't build by default. This can be mitigated if the templates put the OS version in the TargetFramework, but then you end up having the same issue for the next Xcode release: since the OS version is hardcoded, we keep trying to use the older workload, so it'll have to be continuously updated.

An update to the .NET SDK can mean that a package no longer supports being consumed by older SDKs.

Not quite: package authors would have to be explicit about the target platform versions.

dotnet/sdk#30103 is about making that possible (right now we're neither here nor there: we don't support building with older SDKs, neither explicitly nor implicitly).

Also note that package authors aren't often affected by the Xcode incompatibilities (they mostly show up when building apps, not packages).

[dsplaisted]

I think you don't necessarily need to put both the .NET version and the platform version in the package ID. You could just put one of them in the package ID and use the package version to represent the other one. It's probably also fine to put both of them in the package ID if that makes things simpler.

[rolfbjarne]

I think you don't necessarily need to put both the .NET version and the platform version in the package ID. You could just put one of them in the package ID and use the package version to represent the other one. It's probably also fine to put both of them in the package ID if that makes things simpler.

Putting both the .NET version and the platform version in the package ID makes it possible to have branches update eachother using darc.

Example with 2 brances:

• release/7.0.1xx: ships the package Microsoft.iOS.Sdk.net7.0_16.0.
• release/8.0.1xx: ships the packageMicrosoft.iOS.Sdk.net8.0_17.0, and still supports building with the "net7.0-16.0" target framework.

The release/8.0.1xx branch can have a darc subscription on the Microsoft.iOS.Sdk.net7.0_16.0 package to be automatically updated whenever something is fixed in that branch.