Catalog OS known issues

[richlander]

New OS versions may expose behavior changes that can cause existing apps to break. Users often log issues when they experience such problems, in particular for the container images we ship, which deliver the OS and .NET as a single artifact. In many cases, users cannot determine the root cause and look to us for support. Tracking issues often include user-provided workarounds (endorsed by us or not) and those can prove useful. We have a responsibility to make it easy to find these issues so that users who come later can use previous findings to self-diagnose and -address problems.

These issues are distinct from .NET compatibility breaks, which users observe upgrading from .NET version n to .NET version n+1 (or more than +1). When a user observes a break in behavior when upgrading from OS version n to OS version n + 1, we consider that an OS known issue. In some cases, it makes sense for .NET to adapt to those changes and in other cases not.

We need a good place to catalog OS known issues. dotnet/core is likely the best location.

Examples:

• Debian 12 no longer configures OpenSSL to support TLS 1.0/1.1 #6039
• Could not find file '/usr/share/zoneinfo/Europe/Kiev'. #6072
• Add Y2038 related breaking change notices docs#40669

@gewarren and I have come to the conclusion that .NET Learn Docs are not the appropriate place for this information. It doesn't scale and it's not the information most people expect to read there. To her credit, @gewarren saw this problem much earlier than me.

We could use dotnet/core for this. We already have a bunch of OS-specific info there. That's probably the best choice. I'm thinking that we create a breaking change area in the existing OS issues and then link to issues in the relevant repos. We can then point people to the OS issues when they run into trouble. We could potentially create a "Compatibility" sub-issue.

Example: dotnet/core#9583

One key observation is that these breaks tend to apply to all the distros, in a staggered fashion. The same issue may show up in Debian 12 and then Ubuntu 24.04, for example.

[ericstj]

I don't object to having a place to record this information. I'd say it's more of "known issues" rather than "breaking changes". When I hear "breaking changes" I expect to be in control of those and for the list to be particularly complete. I don't think we can commit to such completeness for OS breaking changes, but it does make sense to organize such known issues in a central place with a consistent set of metadata.

I'm OK with dotnet/core as the repo.
For format/metadata - title, impacted API/Scenario, OS versions, .NET Versions, recommended change/workaround, link to any relevant issues. I would imagine that in these cases there should always first be a consideration of "could we deal with this so our users don't have to" and the link to the issue should have a reasonable explanation of why we can't.

[richlander]

Agree on all points. I changed the name of the issue in response. Excellent insights.

I cleaned up the text a little to make it more amendable to link to this issue as our plan.