.NET Target/Runtime Support Proposal

[paulirwin]

As you all know, we are working on getting our final beta done (beta 18) before doing probably at least a RC version, leading up to a final release of 4.8.0. There is the likely possibility that we will need to do a subsequent release to the 4.8.x series with bug fixes, and then of course we also want to do a new major version after that to catch up to latest Lucene. But one or more of those might come a year or more later, after some of the runtimes/targets we support in 4.8.0 are now out of support by Microsoft/GitHub, which could make it difficult to support our automated tests for those runtimes/targets. As far as I can tell, we don't have a process for deprecating or removing runtimes or targets, and I think we should have one so people know what to expect.

A note about runtimes versus targets: I think we would likely not plan on removing a target from a patch release (i.e. 4.8.x or 4.8.0.x where x > 0), unless anyone disagrees. But we might have to remove which runtimes we support to test that target. .NET Standard is only a target and not a runtime, for example, but we can't reasonably test all runtimes that support that target. .NET 8 is both a runtime and a target, and we might have to drop automated test support for that runtime after it goes out of support, while maintaining the built target in the NuGet packages until the next major release.

I think we could do something similar to Rust's Target Tier Policy. This approach would mean we could put unsupported-but-still-building targets in Tier 2, while the supported targets would be Tier 1. So it would be somewhat orthogonal to versioning, at least in the sense that there's not a direct correlation between versions and tiers, as the tiers are based on calendar time expiration of supported runtimes, and versions are whenever we can get them done. Once GitHub/ADO no longer supports installing the SDKs without warnings for any runtimes for that target, the target would move to Tier 2. We would no longer run tests in the CI build for them, but would still build the assemblies (because that can be done by a newer SDK). Anyone still using that target would be on their own to ensure compatibility with updates, and can file issues if needed. I don't think we need a Tier 3 (meaning, it won't build but code is in the repo if you want it) at this time. But moving a target to Tier 2 allows us to more easily run just the tests on platforms that are supported, while still leaving the target in the build so that it isn't a breaking change (at least intentionally). It also flags the target for removal at the next major release.

For each major release (including 4.8.0 being the first major-bumped release in the 4.x series), all targets included with the release must be Tier 1. Then, a subsequent patch release (i.e. 4.8.0.1) might have to move a target to Tier 2 while still being included in the NuGet packages of the release.

What Tier 2 looks like in practice would be pretty simple: don't change the code or conditional compilation, as .NET will still build that target in the pipelines and on our local developer machines. But we would remove the runtime(s) that test it from our automated and local tests. We would welcome and encourage community members that are still using those targets to test independently and file issues as needed. I also expect this to likely only be an issue with .NET 8+ for the foreseeable future, as .NET Framework is (unfortunately, IMO) going to be supported by Microsoft for a while longer.

At the next major release, any lingering Tier 2 targets would be removed from the codebase, including any conditional compilation FEATUREs that only apply to them, to clean up as we go. In this way it's a little different from Rust, as they don't necessarily plan to deprecate/remove every Tier 2 target, but in our case we would since this would only apply to no-longer-supported .NET runtimes.

Also, I think our policy should always be to support the latest modern .NET GA runtimes and targets, even adding support for them in patch releases. So when .NET 10 comes out, we should support it. Note that recently Microsoft announced that .NET STS releases are now supported for 24 months which IMO changes the equation on supporting STS releases, as we won't have to remove support for it at an awkward 6-month-after-LTS interval. I think we should now consider always supporting the latest STS release as not just a runtime for tests, but also a target, once released. With the STS release falling out of support on the same day as the prior LTS release, both would simultaneously follow the process above. As a hypothetical example, if Lucene.NET 4.8.0 ships supporting .NET 8-10 (in addition to the other targets), we would add .NET 11 support in a 4.8.x next November assuming we're still supporting 4.8.x, and at that time drop automated test support for .NET 8 and 9 while keeping all net8.0-net11.0 targets in the release.

For users, what this looks like in practice, is that they can expect that any patch releases will still have at least the same targets available as the .0 release in that major version (and possibly additional new ones), but they should check our updated Tier list at each patch version upgrade to know if it is still officially supported by our test suite. This only really applies to users that absolutely must still run the app on older, unsupported-by-Microsoft runtimes - which, based on my latest poll, I expect to be few and far between.

If this sounds good for everyone, we can create an issue and then PR to get this into the README/docs. But I wanted to open this for discussion. I'm very open to ideas and feedback, but wanted to give a starting point. Thanks!

[rclabo]

Paul - thank you so much for all you are doing to get the project closer to a final 4.8 release.

This seems like a well-thought-out plan, and from my perspective, it exceeds expectations. I can certainly imagine not even including unsupported targets in a patch release, even if that target was supported in the release being patched. That said, the approach you laid out seems like a nice balance of going the extra mile without (hopefully) becoming too burdensome (since there is no attempt to test an unsupported target).

Thank you for putting so much thought into this and communicating it so well.

[kjac]

This sounds like a great plan indeed. This is exactly the kind of clarity and predictability we as downstream consumers appreciate ❤️

My only concern is the same as @rclabo voices to a point - that of your well-being. Don't break your neck trying to support old and unsupported runtimes for ages. It's commendable for sure, but not strictly required in my view.

To get the target clean-up going a little faster, you could consider aligning your major version increment with that of .NET. We've been quite happy with that versioning strategy for the Umbraco CMS. Although a new major every six months is potentially a lot of release overhead, it has the added benefit of allowing for faster deprecation and removal of undesired code (and targets in this case). This of course is a whole new discussion, so just consider it a well-meant input 😃

[paulirwin]

Thanks for the feedback! And I appreciate the note about well-being.

We don't really go out of the way to support unsupported runtimes as .NET Framework 4.6.2 and later is still technically supported. Honestly, if it were up to me alone, I'd drop .NET Framework/Standard support yesterday. I haven't been shy about saying that in other GitHub issues 😆 If put up to a vote, I think everyone knows how I would vote. But I'll go with the flow of what the community wants.

That said, my recent poll shows that people are still using .NET Framework 4.8.x at least. And we got feedback that people are using the .NET Standard 2.0 target to migrate their libraries to support modern .NET. So I think for the Lucene.NET 4.8.x releases at least, .NET Framework/Standard support of some kind is still on the table. (.NET Standard 2.1 can likely be dropped for this release, since it doesn't help with a .NET Framework migration at all, and really only Unity is the last supported target that isn't superseded and even it can use .NET Standard 2.0 if there's anyone out there using that.)

I do hope that Lucene.NET 4.8 is the last release to have to support .NET Framework and .NET Standard so that we can move forward. Something has to get people to finally get off of .NET Framework and upgrade, and I'm okay if that is that they can't upgrade to Lucene.NET 11 in the future 😉

As far as versioning goes, I think our current strategy of aligning the version number to the Lucene version being ported still works for the foreseeable future. But if there's significant community interest in changing that, we'd certainly be open to considering it post-4.8.