Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Package scope migration plan #795

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Package scope migration plan #795

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54b7f42
commit package namespace migration plan
May 13, 2023
3e7506a
s/namespace/scope
May 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions package-namespace-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Node.js Package Scope Migration Plan

Packages intended to be used directly by general developers should be published under the `@nodejs` scope. Packages intended to be used only by Node.js contributors should be published under the `@node-core` scope.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not a big deal, but why not nodejs-core?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See discussion here: nodejs/TSC#1178

Adding this to PR description

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha. I don’t see any reasons there to avoid the consistency, but it’s not a big deal either way.


Packages that already exist and are used directly by general developers, i.e. `undici`, should be cross-published to the new scope and existing name. It should remain this way until the *next major* version is released, in which case the existing name should be *deprecated* and instruct users to start the upgrade path to the new major using the new scope.

For example, take the `undici` package. At the time of writing this document, the `latest` version is `5.22.0`. If we were to create the `@nodejs` scope today, we would start cross-publishing to `@nodejs/undici` and `undici`. We would continue this until `v6` was to be released. Lets say that `5.35.7` is the last `v5` version of `undici`. `@nodejs/[email protected]` and `[email protected]` would both be published, but `[email protected]` would be marked as *deprecated* using `npm deprecate [email protected] "Upgrade to @nodejs/undici for version 6"`

Packages that already exist and are only used by Node.js contributors, i.e. `node-core-utils`, should be immediately deprecated, and republished under the new scope. This process is different from the other scope because these packages tend to have less users, and are often not used as a part of another application or library. Otherwise stated, by deprecating the latest version, there is a low or non-existent chance of breaking a legitimate application. And contributors would be well communicated with about the change. Finally, if these tools specify a certain `bin` name, they can (and should) continue to use that name.

For example, `node-core-utils` could be republished as `@node-core/utils`. The `bin` values of `get-metadata`, `git-node`, and others can all remain the same.