search

npm / rfcs

Public change requests/proposals & ideation
Other
730 stars 239 forks source link

[RRFC] Improving workspace terminology #430

Open jasonwilliams opened 3 years ago

jasonwilliams commented 3 years ago

Motivation

Based on discussions from https://github.com/npm/feedback/discussions/510 and a few other issues.

The purpose of this issue is to resolve the confusion of using the term "workspace" or "workspaces". There are contradictions among the RFC which interchanges between packages and workspaces. RFC: https://github.com/npm/rfcs/blob/latest/implemented/0026-workspaces.md

For e.g I believe a workspace is the top-level folder which holds all of the packages that you work in. But the child-projects which can be published to npm are packages. The community seems to settle on this also: A workspace is what npm calls a monorepo: A directory with subdirectories that are npm packages. https://2ality.com/2021/07/simple-monorepos.html#npm-workspaces

In dictionary we have a definition:

workspace: A nested package within the Top-level workspace file system that is explicitly defined as such via workspaces configuration. Top-level workspace: The root level package that contains a workspaces configuration defining workspaces.

So my understanding here is top-level workspace is a package that containers configuration defining more (inner) workspaces. So it sounds like the inner packages are also called workspaces?

Examples

The example lists them as packages.

{
    "name": "workspace-example",
    "version": "1.0.0",
    "workspaces": {
        "packages": [
            "packages/*"
        ]
    }
}

So are they packages or workspaces? The summary of the RFC calls them packages also:

Add a set of features to the npm cli that provide support to managing multiple packages from within a singular top-level, root package.

and the motivation

The primary motivation behind this RFC is to fully realize a set of features/functionality to support managing multiple packages that may or may not be used together.

Desired Behaviour

"Workspace" refers to the outer folder which holds the packages, and "package" refers to each individual package residing inside the workspace. "top-level workspace" no longer needs to exist. The code used in the package.json already follows this convention (see above) so its mostly updating the RFC.

Shipping Changes

There should be no changes to the functionality of Workspaces.

References

https://github.com/npm/rfcs/pull/103

ljharb commented 3 years ago

Specifically, if the qualifier “root” and/or “child” is necessary to disambiguate the term “workspace”, then it is far from an ideal choice.

isaacs commented 3 years ago

https://github.com/npm/feedback/discussions/510#discussioncomment-1155331

isaacs commented 3 years ago

Comments from rfc call: