search

rdfjs / types

Authoritative TypeScript typings for all RDFJS specifications
MIT License
17 stars 13 forks source link

Correct package.json name to rdfjs org #4

Closed blake-regalia closed 3 years ago

tpluscode commented 3 years ago

What is the benefit of this change? Keeping the name rdf-js will not require any changes in code.

If we do this, however, everyone will have to update all of their imports.

blake-regalia commented 3 years ago

Nothing has to break, we can publish over rdf-js to proxy this package. Bringing the package under the rdfjs org aligns it with this repo and signals that it is endorsed and maintained by the RDFJS team.

matthieubosquet commented 3 years ago

That sounds awesome, I do agree it would bring clarity and consistency!

I still find it hard to find my way through the RDF JS ecosystem and its many libraries. Having an authoritative namespace under which a few packages are maintained and considered canonical implementations is a big plus to not be discouraged. As a developer, I find it much more intuitive and less confusing to install @rdfjs/types which I know is endorsed by the Community Group.

Also, rdf-js was last published two years ago anyway and this is a major release so for someone updating their types, the simple action of installing a new package seems like a fairly small overhead. Which brings me to think it's a sensible time to do it.

tpluscode commented 3 years ago

So we then agree to publish both rdf-js and @rdfjs/types?

matthieubosquet commented 3 years ago

Alternatively, rdf-js could be deprecated and point to the newer @rdfjs/types for people wishing to update to the major version 2.x of the types. I think that solution would defuse potential confusion and allow people to organically discover that the types have a new major release and slowly migrate to the canonical URL rather than having rdf-js linger around forever.

The other question that seemed more important is how to proxy @types/rdf-js to the canonical/authoritative @rdfjs/types. It seems unclear what the best way forward in that matter is. But I don't think it should hold off publishing @types/rdf-js.

tpluscode commented 3 years ago

Alternatively, rdf-js could be deprecated

I'm still not convinced. Keeping rdf-js does not break anyone's code. Even if it's only s/rdf-js/@rdfjs\/types/ I think it's unnecessarily disruptive. All everyone would otherwise change is the package.json entry

The other question that seemed more important is how to proxy

You mean what happens when we finally start publishing our own package? I have not experienced it first hand as typings author but Definitely Typed has a policy for removing packages. They recommend removing the @types/ package as soon as we publish our own. At which point I think an empty package is published with deprecation warning on npm install.

matthieubosquet commented 3 years ago

The current situation is already disruptive since there are two concurrent packages rdf-js and @types/rdf-js and in fact, on the homepage of the rdf-js package it clearly states: "Do not install this package directly". See: https://www.npmjs.com/package/rdf-js

As a result and for the past 2 years, I think most people (including me and most of the recent repositories I've encountered) have been relying on @types/rdf-js, not on rdf-js. If removing the @types/rdf-js package is ok in your opinion, I don't see how deprecating rdf-js is a problem in comparison.

First, deprecating rdf-js will not force anyone to update their dependency, once again to a new major so not an automatic update anyway, it will instead show a deprecation message when they install it incentivising them to install the authoritative/canonical package. See: https://docs.npmjs.com/using-deprecated-packages.

Second, there is nothing in the rdf-js package name that hints towards the fact that it is a types library rather than an implementation of the RDF/JS specification. It confused everyone I've talked to.

Third, The brand name RDF/JS is a great asset, it would be a shame not to use it. Including it in the package name makes the endorsement/source clear and it's very helpful/reassuring, even more so to new developers of which we can only hope there will be more in the future.

Thanks for the link to the policy for removing packages on DefinitelyTyped, it makes things clearer. Great to see that this process properly deprecates @types packages and links them to the relevant repo. See: https://www.npmjs.com/package/@types/3d-bin-packing

tpluscode commented 3 years ago

Curious that I have never experience the confusion you refer to. Let me give you a complete example.

I think most people have been relying on @types/rdf-js, not on rdf-js.

You only consider package.json? Any project using the types will install @types/rdf-js, which pretends to be type declarations for rdf-js. (The fact that this package actually exists is right now irrelevant).

Thus, in code you will find imports like:

import { NamedNode } from 'rdf-js'

By reviving rdf-js for the types no code will have to change. The next patch release of @types/rdf-js will simply install rdf-js as its dependency and thus all other @types packages which depend on RDF/JS spec (for example type for parsers/serializers) will continue to seamlessly work because all of their imports will still be valid.

If removing the @types/rdf-js package is ok in your opinion, I don't see how deprecating rdf-js is a problem in comparison.

Again, the current package will not be removed. It will simply proxy to a new "real" package to ease adoption. How it "is a problem in comparison"? Read below

Now, changing the name to @rdfjs/types will completely break everyone. I expect that the necessary updates will create a snowball effect and it will likely continue until everyone migrates to the new package.

The problem is similar to what can happen if you somehow end up with multiple versions of @types/rdf-js. Duplicate declarations of type can be falsely identified as incompatible in weird places in your modules, preventing successful build.

So while I agree that if we were starting from a clean slate, I too would opt for a more natural, less confusing package name, at this point we do not have that luxury. We're looking at an existing ecosystem which we cannot afford to break and that should trump the arguments about people being confused.

tpluscode commented 3 years ago

Nothing has to break, we can publish over rdf-js to proxy this package.

@blake-regalia, so you propose to publish rdf-js with a single index.d.ts module?

export * from '@rdfjs/types`
rubensworks commented 3 years ago

Apologies for the late reply, but I agree with @tpluscode's stance on this.

Using this other package name will be break all existing packages, requiring them to change all imports. Whereas just migrating to rdf-js would allow people to keep all of their existing code unchanged (and be compatible with other packages that have not yet been updated to the new typings).

So I'm against merging this PR.

blake-regalia commented 3 years ago

Coming back to this thread, I suggest we deprecate the other packages and point to o@rdfjs/types as the single source of truth for RDFJS typings. Package deprecation is not a big deal guys. Let's clean this up once and for all.

tpluscode commented 3 years ago

@blake-regalia you agree with my https://github.com/rdfjs/types/pull/4#issuecomment-747949752 ?

As long as we won't have everyone change their imports right away I can agree with what happen's here

blake-regalia commented 3 years ago

I initially proposed making rdf-js a proxy lib, but then we would have to maintain two packages in order to keep semvers up to date. I believe the more appropriate course of action here is to simply deprecate the other package and point users to the scoped package @rdfjs/types. Keep in mind, nobody's code will break. When they are ready to migrate then they can do so.

More technically: I would propose publishing a new minor semver version of rdf-js and then immediately deprecate only that version. This would ensure that when a user installs a module that depends on rdf-js they are not met with a deprecation message. When developers are ready to upgrade however, then they can perform migration.

tpluscode commented 3 years ago

Word of caution

The proxy package could just have a single version and a dependency on "@rdf-js/types": "*". Actually trying to use sem ver is asking for trouble. Conflicting versions of multiple types versions easy lead to weird npm/yarn resolutions and broken build. We had a long discussion about @rdfjs/data-model which had a dependency on a specific version of the types. It was a constant issue until it became a "star" dependency. (https://github.com/rdfjs-base/data-model/pull/24#discussion_r479949230)

blake-regalia commented 3 years ago

Started an open discussion in DefinitelyTyped gitter channel to clarify the removal/deprecation process here: https://gitter.im/DefinitelyTyped/DefinitelyTyped?at=609382c70845c416dcc8497b

blake-regalia commented 3 years ago

After a productive discussion with @tpluscode - I agree with the proxy package which has a wildcard dependency on the @rdfjs/types package.

I will be merging this PR now that we have resolved how to proceed with the DefinitelyTyped package.

tpluscode commented 3 years ago

I believe we need a new repo for rdf-js and publishing setup? @rubensworks, you previously published that on NPM...

rubensworks commented 3 years ago

I believe we need a new repo for rdf-js and publishing setup?

Isn't that the purpose of this repo here? Also #3.

@rubensworks, you previously published that on NPM...

That's just a stub package, we can easily publish over that when we get to that point :-)

tpluscode commented 3 years ago

Isn't that the purpose of this repo here?

In which case I come back to proposing a monorepo, albeit with one of the two packages really not changing much, and changesets to make publishing easy for maintainers

when we get to that point :-)

we are very close to that point

rubensworks commented 3 years ago

one of the two packages

What packages do you have in mind? I see only one package (the one coming from @types/rdf-js).

tpluscode commented 3 years ago
  1. @rdfjs/types -> the real one we have here right now
  2. rdf-js -> a proxy package
rubensworks commented 3 years ago

Ah ok, so actually there will be 2 proxy packages: @types/rdf-js will be a proxy to rdf-js, and rdf-js will immediately also be a proxy to @rdfjs/types. Thanks for the clarification!

Since rdf-js should not need further changes after its initial release, it might be better to just have a separate repo for this, which we can then ignore.

tpluscode commented 3 years ago

Since rdf-js should not need further changes after its initial release, it might be better to just have a separate repo for this, which we can then ignore.

Yes, also an option :)

blake-regalia commented 3 years ago

Sounds good to me