Merging NATS .NET Client Library v1 and v2 Packages into a Unified >v2.4.x

[mtmk]

This pull request consolidates the NATS .NET client libraries' v1 and v2 functionalities into a unified set of packages under the nats-io/nats.net repository. The primary goal is to offer both v1 and v2 functionalities within the NATS.Client package while centralizing package management and promoting v2 features.

This change does not impact existing v2 applications, except when referencing NATS.Net package in which case there will be minor dependency changes explained below.

Note: Merging this PR won't publish NuGet packages. That will be done in a follow up PR.

Key Changes

NATS.Client Package:

• Includes the v1 codebase and references NATS.Client.Simplified, NATS.Client.Core, and NATS.Client.Serialization.Json.
• Ensures seamless access to v2 functionalities for new users of this popular package, while maintaining backward compatibility with v1 projects.
• V1 users upgrading to NATS.Client 2.x.x can continue using v1 functionality without worrying about breaking changes.
• If v2 users want to use JetStream, they will need to add the NATS.Client.JetStream package, which is a natural step for developers familiarizing themselves with the ecosystem.

NATS.Client.Simplified Package (new):

• Provides a simplified API to address serialization setup complexity for common use cases.
• References NATS.Client.Core and NATS.Client.Serialization.Json.
• The package simplifies the transition without altering references in other packages, such as NATS.Client.Core, to maintain AOT support and avoid introducing the NATS.Client.Serialization.Json dependency.
• Although it is possible to suppress AOT warnings for trimming, changes to v2 packages are minimized for stability and compatibility.

NATS.Net Package:

• Includes referential changes by incorporating NATS.Client.Simplified and NATS.Client.Serialization.Json.
• Promoted as the main package for NATS .NET users to avoid v1 baggage and prevent confusion for new users.
• Designed for use in examples and simpler projects where additional dependencies are acceptable.

Namespace Clashes:

• Namespace clashes are minimal and limited to a handful of classes in NATS.Client.JetStream. Since v2 classes also follow the Nats* prefix convention type name conflicts are avoided.
• The new NATS.Client.Compatv1v2.Test demonstrates and confirms that namespace clashes are not an issue.

Target Framework Changes (v1):

• Targeting only netstandard2.0 for v1 users, dropping netstandard1.6 and net46 targets.
• Upon upgrading to NATS.Client v2.x.x, v1 users will pull down three additional DLLs:
  • NATS.Client.Core.dll (473 KB)
  • NATS.Client.Serializers.Json.dll (9 KB)
  • NATS.Client.Simplified.dll (10 KB)
  • Plus System.Text.Json, alongside the main DLL NATS.Client.dll (609 KB).
• The motto of no dependencies for v1 is somewhat relaxed, but users can drop these dependencies if needed since the references enable v2 usage without requiring any functionality from the additional dependencies.

Benefits

• User Experience: By merging v1 and v2, users downloading NATS.Client via Visual Studio will seamlessly use v2 functions as documented, without surprises. NATS.Client will primarily serve developers who access NuGet directly without consulting documentation.
• Obsolete APIs: This provides an opportunity to start marking v1 APIs as obsolete, guiding users towards modernized practices.

Rationale

This unified approach allows us to streamline user support, improve adoption rates, and simplify the transition process for existing users. By maintaining a single set of packages, we enhance user experience while ensuring that the most popular package on NuGet continues to serve its existing user base effectively.

Request for Feedback

Please review the proposed changes and provide your feedback. We aim to address any potential issues and ensure a smooth transition for our users.

[rickdotnet]

I copied V1 code into my V2 project and it worked no problem. This approach seems to provide the least bumpy transition, imo. LGTM!

[scottf]

1. Is there is a technical reason to do this, such as a V2 user cannot also use V1?
2. Do we have actually have evidence that people are being driven to V1, (accepting that it can happen). Are the other ways such as documentation that we don't already have that can help this.
   • I did a web search on google / duck duck go / bing for "NATS dotnet client", "NATS dotnet nuget", "NATS C# client" and V2 is the most prominent, sometimes V1 isn't even on the first page.
   • Search for "NATS C# nuget" in google / ddg have V1 link on top but then V2 links. Bing has V2 on top.
   • The search results were clear that everything is part of NATS.IO.
3. We are going to have to maintain and improve V1 for at least 2 years if not 5, in which time, we won't have any issue with number 2.
4. Could this negatively affect existing V1 users. We've already pulled the rug out on them for the repo change (which I agree was necessary,) but they will have to change their nuget versioning to deal with version 2. Seems confusing.
5. We lose the granularity of versioning minor and patch applying specifically to v1 or v2.

[mtmk]

1. Is there is a technical reason to do this, such as a V2 user cannot also use V1?

no. we're trying to leverage NATS.Client popularity to increase v2 / NATS .NET adoption.

2. Do we have actually have evidence that people are being driven to V1, (accepting that it can happen). Are the other ways such as documentation that we don't already have that can help this.

   • I did a web search on google / duck duck go / bing for "NATS dotnet client", "NATS dotnet nuget", "NATS C# client" and V2 is the most prominent, sometimes V1 isn't even on the first page.
   • Search for "NATS C# nuget" in google / ddg have V1 link on top but then V2 links. Bing has V2 on top.
   • The search results were clear that everything is part of NATS.IO.

it's confusing for people. search on https://www.nuget.org/

3. We are going to have to maintain and improve V1 for at least 2 years if not 5, in which time, we won't have any issue with number 2.

that is really what we're to do. trying to accelerate that time.

4. Could this negatively affect existing V1 users. We've already pulled the rug out on them for the repo change (which I agree was necessary,) but they will have to change their nuget versioning to deal with version 2. Seems confusing.

yes. it's v1 users who will be affected an need support, but once this is done then everyone will be on the same page more or less, rather than having confusing nuget packages for another 5 years.

5. We lose the granularity of versioning minor and patch applying specifically to v1 or v2.

that is true. we already have multiple packages with v2 and the management approach is to keep them all on the same version to avoid version compatibility matrix etc. I don't believe it would be a problem especially considering the release frequency of v1.

[scottf]

So I don't agree with the answers to (1) and (2). Based on web search, we know that it's not an issue. Based on Nuget, V1 comes up first in the listing, V2 is 4th, 5th and 6th, and matches the name NATS.Client which is really confusing to me since I would think that's part of V1. (Which I realize is an argument for the change, but that problem was created/pre-existing.)

(3) Doesn't matter where the code is, the customer is just putting the software in the field this year, 5 years doesn't seem out of the question.

(4) Maybe it won't negatively affect V1 users. Maybe it will actually encourage migration. I'm not actually sure how this pushes the needle either direction.

(5) Consider if you will, an application using 1.1.6 (the current V1). Now there are bug fixes and features that get added to v1 and we would have minor versioned it. 1.2.0 doesn't exist but 2.x.x does. Wait a second, I have to MAJOR version to get these fixes. At this point I'm unaware that the V1 api is fully supported in V2, and the changes are part of V2. This is a major barrier to entry, it's almost like support is completely gone. Sure, I could RTFM, but who does that. I think you see where I'm going.

---

At the end of the day 2 things. 1) Maybe I'm making a mountain out of a molehill, it wouldn't be the first time. 2) If the decision is to make this change, I'll live with it and I'll support it. There will or won't be issues, if there are we'll just deal with it.

[aricart]

I chatted with @mtmk for quite a while, and we agree that on this particular release it probably doesn't matter - however it does make semver not useful (except when tagging outdated). My preferred would be that 2.x doesn't include 1.x, and share the Nuget name, but are API major version change - either way there will be some issue either way.

[scottf]

Along the same lines as Alberto...

• Don't combine the repos (don't combine V1 into V2)
• Share the Nuget name

The upside of this is that V2 gets the benefit of V1 in the Nuget directory. The downside is that any V1 developer that has automatic updating of Nuget probably will fail a build. But I can't think of anyone who does that. Thinking about our 3 biggest corporate customers, they will never upgrade versions automatically, they will only ever upgrade to a specific version.

This also eliminates the semver issue as both will be completely independant.

[mtmk]

Along the same lines as Alberto...

• Don't combine the repos (don't combine V1 into V2)
• Share the Nuget name

The upside of this is that V2 gets the benefit of V1 in the Nuget directory. The downside is that any V1 developer that has automatic updating of Nuget probably will fail a build. But I can't think of anyone who does that. Thinking about our 3 biggest corporate customers, they will never upgrade versions automatically, they will only ever upgrade to a specific version.

This also eliminates the semver issue as both will be completely independant.

This was the original suggestion now we came full circle back to #600

to reiterate this is making life easier for v1 users. some will try to update to latest. why break their code regardless of what we might think about semver?. second we will have to make sure we only publish a meta NATS.Client package from v2 not to break it for projects using both and users need to be careful with the versions numbers of NATS.Client and not use v2 of that package if mixing both APIs for some reason. Just to thrown in the mix they might be using other packages that require v1 and v2 which might lead to unresolvable package conflicts.

so the down side is we're going to make an extra release once in a while.

[dalmuti509]

Along the same lines as Alberto...

• Don't combine the repos (don't combine V1 into V2)
• Share the Nuget name

The upside of this is that V2 gets the benefit of V1 in the Nuget directory. The downside is that any V1 developer that has automatic updating of Nuget probably will fail a build. But I can't think of anyone who does that. Thinking about our 3 biggest corporate customers, they will never upgrade versions automatically, they will only ever upgrade to a specific version.
This also eliminates the semver issue as both will be completely independent.

This was the original suggestion now we came full circle back to #600

to reiterate this is making life easier for v1 users. some will try to update to latest. why break their code regardless of what we might think about semver?. second we will have to make sure we only publish a meta NATS.Client package from v2 not to break it for projects using both and users need to be careful with the versions numbers of NATS.Client and not use v2 of that package if mixing both APIs for some reason. Just to thrown in the mix they might be using other packages that require v1 and v2 which might lead to unresolvable package conflicts.

so the down side is we're going to make an extra release once in a while.

DON'T Share the Nuget Name either

It is fine to not combine repos, but you cannot have namespace/dll/nuget collisions between the v1 and v2 client repos. If you do you cause the issue called out in #600 (comment) even if the version number is properly updated to 2.x or anything else since .Net only allows one dll to be named Nats.Client.dll. v1 can be Nats.Client and v2 can be Nats.Net just fine.

In larger companies, the library developers and service developers are often on different teams/orgs/regions and having nuget/dll overlaps can cause significant cost to the orgs when one team decides to begin using the v2 client and another team does not. Having an overlap effectively creates a production blocking bug to all .Net services that use NATS.

[mtmk]

see #600