Anti-Update practices

[RaHorusFreak]

Hello team,

It's both frustrating and ironic to see how updating to Microsoft.OpenApi 2.0 ends up breaking an entire solution without any notice, warning, change log, or similar documentation. It's as if the update process has become: try it, if it breaks — revert; if it doesn't — you're lucky. These practices are steadily eroding the .NET ecosystem. Please, when similar changes are introduced, at the very least there should be explanations and actionable solutions offered to address such disruptive issues.

[baywet]

Hi @RaHorusFreak
Thank you for using the SDK and for reaching out.
Did you happen to find this page?
https://github.com/microsoft/openapi.net/blob/main/docs%2Fupgrade-guide-2.md

[madhon]

Hi @RaHorusFreak Thank you for using the SDK and for reaching out. Did you happen to find this page? https://github.com/microsoft/openapi.net/blob/main/docs%2Fupgrade-guide-2.md

That page doesn't address the breaking caused in the integration with Microsoft.AspNetCore.OpenApi, eg document transformers due to the type changes/removals

[Frulfump]

Maybe that will be produced as part of this issue #2426. Strange to not have that in place before releasing 2.0.0 GA.

[madhon]

Maybe that will be produced as part of this issue #2426. Strange to not have that in place before releasin 2.0.0 GA.

That issue only talks about documentation so cant see how as it requires code changes in the aspnetcore side to account for the breaking changes in this repo

[Frulfump]

(Not stale). To be fair I expect breaking changes when it's a new major release even tough not everyone follows semver 2. But as pointed out there should be docs to explain how we should absorb them, especially since ASP.NET Core is a large user of this package.

[baywet]

Hi everyone,
Thank you for the additional information.

Any issue with with aspnet open API package should be filed in this repository instead https://github.com/dotnet/aspnetcore

The aspnet team is working hard to upgrade to microsoft.openapi 2 as part of dotnet 10.

If you are using net < 10, you should remain on version 1.X of this package.

I agree the upgrade guide should clarify that aspect as this is one of the main scenarios for this library. Would anyone volunteer a pull request?

[Frulfump]

@baywet Do you mean ASP.NET Core < 10? As that's a bit different from < .NET 10.

And if it's actually .NET 10 then why is the TFM net8.0 here https://www.nuget.org/packages/Microsoft.OpenApi/2.0.0#dependencies-body-tab if you must use net10.0? Shouldn't that be net10.0 then, would make it clear that you can't use net8.0 or net9.0 i.e you would get errors I think (or would it fall back to the netstandard2.0 support then?)?
(Not sure but I think you could write an analyzer to see if it's used within ASP.NET Core < 10.0)

I could do a PR if I just knew the circumstances where it's actually supported a bit better.

[baywet]

Yes, thank you for calling this out. I meant aspnet 10 not net 10.
Happy to review any PRs any of you would send out way

[Frulfump]

Created a PR here #2451

[baywet]

Thank you. I've just reviewed it and it should get merged shortly.

Beyond that, was there any other grief on this issue?