[Breaking change]: GetOSVersion on MacCatalyst now normalizes the build component to 0 if undefined (-1)

[kotlarmilos]

Description

This update ensures that MacCatalyst version components retrieved from the OS are always normalized to three components: major, minor, and build. The build component is set to 0 if undefined (-1), ensuring consistent behavior between iOS and MacCatalyst versions for version checks.

dotnet/runtime#108694

Version

.NET 10 Preview 1

Previous behavior

The build component in Version was not previously normalized, which led to incorrect version checks on MacCatalyst when only two components (major and minor) were provided. This resulted in invalid version checks.

New behavior

The MacCatalyst build component is now normalized to 0, ensuring consistent version checks. The revision component is always set to -1, as it is not specified on MacCatalyst or iOS.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Prevent incorrect version checks and align MacCatalyst versioning with iOS, ensuring consistent version components.

Recommended action

Use versions of up to three components (major, minor, and build) on MacCatalyst.

Feature area

Core .NET libraries

Affected APIs

public static bool IsMacCatalystVersionAtLeast (int major, int minor = 0, int build = 0);
public static bool IsOSPlatformVersionAtLeast (string platform, int major, int minor = 0, int build = 0, int revision = 0);
public static string Environment.OSVersion.Version.ToString()

[jeffhandley]

@kotlarmilos -- To answer a question you asked in email, once the breaking change PR is merged into dotnet/runtime, you do not need to close this issue. The content from this issue will be turned into a breaking change document on the https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes portion of the docs site. The docs team will close this issue once that's completed. We don't yet have a .NET 10 section in the docs.