Consider migration story for @aspnet/signalr

[analogrelay]

TL;DR: If you develop a JavaScript library component that depends on @aspnet/signalr, we'd like to hear from you!

One open question that we'd like some support from the community on is how to manage the name transition. Here, we'd love feedback from app developers and anyone developing other NPM components that depend upon @aspnet/signalr.

My biggest concern is if a library component references @aspnet/signalr at version >=1.0.0. They are saying they work with versions 1.0 and higher, but the problem is that version 3.0 is not part of that set (because it's a different package name).

We have a few options

1. Just stop shipping @aspnet/signalr.
   • Pros: It's easy
   • Cons: People using @aspnet/signalr don't know that we changed
2. Ship one last version of @aspnet/signalr (probably version 3.0) and immediately deprecate it on NPM.
   • Pros: Still pretty easy, clearly tells users they need to update (via the deprecation message)
   • Cons: Libraries taking a dependency on @aspnet/signalr either have to update, or can't get the new stuff
3. Ship @aspnet/signalr as a "shim package". This would be a package that has a direct dependency on the matching version of @microsoft/signalr and re-exports all the types. So it's content would be something like the snippets below
   • Pros: Nobody is broken
   • Cons:
     • We have to maintain this package for some undefined period of time.
     • If an app is already using the new version (@microsoft/signalr) and references a library using @aspnet/signalr version 1.x (BEFORE the shimming), then they may end up with two copies of the library. The 1.x version of @aspnet/signalr and the 3.x version of @microsoft/signalr. Thanks to JavaScript this will probably still work, types can be exchanged just fine.

I think if we did option 3, we'd also mark each release of these shims as deprecated so that NPM users get the warning. That means that if an app did use @microsoft/signalr and a library it depends on used @aspnet/signalr you would get a warning indicating you were in a slightly odd state. If you manually installed the shim package @aspnet/signalr it would fix the odd state since now the library would be using the shim and there'd only be one copy of @microsoft/signalr

@aspnet/signalr package.json

{
	"name": "@aspnet/signalr",
	"main": "index.js",
	"dependencies": {
		"@microsoft/signalr": "[exact same version]"
	}
}

@aspnet/signalr index.ts

export * from "@microsoft/signalr"

[analogrelay]

Another option I just thought of:

4. Retroactively ship @microsoft/signalr shims for the existing @aspnet/signalr packages which just re-export @aspnet/signalr types, like the other proposed shim above.
   • Pros: Anyone at any version can just move to the new package name without breaking existing apps.
   • Cons: I'm actually thinking this is the win-win scenario. We have to ship these weird back-versioned shims but they're stable and never need to be updated. Existing apps/libraries do need to move to the new package, but they can do that regardless of what version they are on.

Thoughts @davidfowl @bradygaster @BrennanConroy @mikaelm12 @halter73 ?

[analogrelay]

I'm leaning hard to option 4 here. It provides a clear migration path for everyone, doesn't require us to keep maintaining shims (since we just ship one-time @microsoft/signalr shims for existing @aspnet/signalr versions) and type identity works fine because JavaScript. We can deprecate all versions of @aspnet/signalr (assuming that doesn't mess with the shimming) to tell everybody to just flip over to @microsoft/signalr

To be clear, these new packages would be one for each currently-released version of @aspnet/signalr, and would look like this:

@microsoft/signalr package.json

{
	"name": "@microsoft/signalr",
	"version": "1.0.0",
	"main": "index.js",
	"dependencies": {
		"@aspnet/signalr": "=1.0.0"
	}
}

@microsoft/signalr index.ts

export * from "@aspnet/signalr"

[bradygaster]

So far I'm with @anurse on option 4 seeming to be the path of least resistance and maintenance.

[BrennanConroy]

And if we patch the npm package will we only update the new @microsoft/signalr package or do both?

[mikaelm12]

And if we patch the npm package will we only update the new @microsoft/signalr package or do both

Yes, this is also my concern. I feel like servicing both will become a thorn in our side.

[mikaelm12]

[Edited] Having @aspnet/signalr have a direct dependency on @microsoft/signalr feels dishonest for lack of a better word. I'm not sure if allowing two ways to get the same version of client in general is the best approach. I'm personally leaning towards just not continuing to ship the @aspnet/signalr package. It will be unfortunate that we'll end up in the same situtation as we have with the java client have both the aspnet and microsoft branded packages published and potentially confusing customers.

[bradygaster]

To clarify, as you mentioned @signalr/signalr so I just want to make sure I got your point, reworded below:

Having @microsoft/signalr have a direct dependency on @aspnet/signalr feels dishonest for lack of a better word. I'm not sure if allowing two ways to get the same version of client in general is the best approach. I'm personally leaning towards just not continuing to ship the @aspnet/signalr package. It will be unfortunate that we'll end up in the same situtation as we have with the java client have both the aspnet and microsoft branded packages published and potentially confusing customers.

I'm inclined to agree with @mikaelm12 philosophically on this, as it does seem weird (like it did years ago when Jeff described a similar pattern in NuGet) to actually be pulling the @aspnet/signalr package when you asked for the @microsoft/aspnet package. However, I think it is the path of least resistance for folks who have taken a dependency.

I'm also thinking of the community that requested we do this; the implication is folks didn't want to use it because of the implication that "ASP.NET is a requirement for SignalR." If we do it this way, the
@microsoft one will actually be the @aspnet one. Curious what those who proposed we do this would say about it - if it doesn't feel dishonest or spicy with them, I'm okay with it provided we agree it's the path of least resistance for customers and ourselves.

[mikaelm12]

Didn't mean @signlar/signalr! My b. Editing it now to read @aspnet/signalr

[bnb]

Hey hi hello 👋

I have some thoughts/opinions that I wanted to share:

I would not recommend doing any kind of mirroring of APIs. It creates a lot more work for a negligible amount of end-user benefit. The amount of work needed to set this up, maintain it, and – most importantly – fix it if anything goes wrong is a much higher cost than any possible end-user benefit that I am aware of. If you want to get into technical reasons, this is not a good path because it effectively gets around npm, yarn, pnpm and any other package manager's deduping of redundant modules which will end up increasing deployment/bundle sizes for end-users.

Having @microsoft/signalr have a direct dependency on @aspnet/signalr feels dishonest for lack of a better word.

I 100% agree. Being totally honest: if I'd seen this before I worked at Microsoft, my assumption would be that whoever did this was not a part of the JavaScript ecosystem and was instead just someone from .NET trying to make the JS folks happy while not really caring about them.

Regardless of the positive intent, it strays from how the JavaScript ecosystem works and comes off as uninformed/unaware – which is definitely not my experience with the SignalR team(s) so far now that I'm at Microsoft.

I'm also thinking of the community that requested we do this; the implication is folks didn't want to use it because of the implication that "ASP.NET is a requirement for SignalR."

Being totally unaware of SignalR before working at Microsoft, this wasn't quite my perception. The perception I had when learning about @aspnet/signalr was that SignalR was only for ASP.NET – meaning I couldn't use it as a Node.js developer. But, I suppose that could technically also be perceived as ASP.NET being a req for SignalR usage.

As a Node.js ecosystem member, I'd like to make a suggestion – definitely weigh the pros/cons but IMO it makes the most sense to me:

Do option 2. Walking through why:

1. No new version needs to be shipped – deprecation can be done directly without shipping a new version. See the docs on npm deprecate. This also doesn't need to be done immediately if we feel it's too disruptive – we could deprecate in 365 days, or any other predefined time that we'd like to settle on.
2. Deprecation is soft, not hard. If there are troubles for specific minor/patch versions we can un-deprecate those if absolutely needed. This should be a last resort that is taken very seriously.
3. Since this is a semver major (two, actually?), most people should theoretically need to update anyway since npm's default is to gracefully allow for semver minor upgrades (see the caret version npm semver documentation, which is default npm behavior). As such, regardless of the scope people would have to be very intentional about upgrading their versions as a semver major version. The only downside here is that automated update tooling like Greenkeeper won't be able to auto-PR the semver major change.

Additionally, I'd like to share some reasons why I'd be extremely hesitant to suggest Option 4:

• You would need to recreate every published version of @aspnet/signalr. If there is one single inconsistency in any/all of the re-publishes, you have 72 hours from publish to either delete it or re-publish because of npm's unpublish policy. This is something I would strongly recommend against.
• The @aspnet/signalr modules will continue to work perpetually – they're not going anywhere, since they're immutable. As such, there's no real need for something like a migration path for those older versions with the new namesapce. If you're using those versions, you point to @aspnet/signalr. If you're using newer versions, you point to @microsoft/signalr. The only kind of migration that should be happening is whatever semver major changes are introduced in the newer version – adding an additional change to a LOC that would have already changed should be theoretically uncontroversial.
  • The caveat here is megacorps that have to approve every dependency manually. That said, my experience is that they typically move at a glacial pace and this is not an abnormal experience – keeping some kind of permanent reference of the historical name in the README.md would be smart for these folks, regardless of which option you go for.

I'm actually thinking this is the win-win scenario. We have to ship these weird back-versioned shims but they're stable and never need to be updated.

• I'm confused how this is different than just using @aspnet/signalr if those are the versions someone is already depending on – changing to @microsoft/signalr for the versions that are currently published actually increases the amount of work they'd need to do, since they already have those versions pointed to the existing working module.

[bnb]

Since I have a lot of friends who maintain a non-trivial amount of packages on npm, I decided to ask about this in a general sense on Twitter. The responses so far have been super interesting:

• general feedback so far is to do many of the steps y'all have already done + use the deprecation message once the new version is published
  • there's a similar example of joy => @hapi/joy that uses a good deprecation message and points to the new one: https://www.npmjs.com/package/joi (thanks Dominik Kundel!)
    • you can also see that none of the previous versions were backfilled in the scoped module: https://www.npmjs.com/package/@hapi/joi

[mikaelm12]

Thanks for your insight on the issue @bnb! Your perspective is really appreciated!

[bnb]

Happy to help, @mikaelm12! ❤️

[manekinekko]

Hey,

I'd like to chime in and provide some feedback–as a member of the JavaScript community and a maintainer/author of some Node packages.

@bnb had already provided a much more detailed response.

So, definitely go for option 1: publish the new package and deprecate the old one, making sure to provide the right communication about this change and how they can get the new package. This, of course, would be considered as a breaking change, so developers would anyway have to check the new API deprecations and update their existing code. In the process, you would have an extra step which updating their package.json with the new scope.

Cheers.