[RRFC] Improving workspace terminology

[jasonwilliams]

Motivation

Based on discussions from npm/feedback#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

#103

[ljharb]

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

[isaacs]

npm/feedback#510 (comment)

[isaacs]

Comments from rfc call:

• @isaacs
  • ~"language is hard"
  • provided feedback/insight in the originating discussions here: Workspace naming is confusing feedback#510
• @darcyclarke
  • has tried to map/visualize these terms as they relate to a
  • Action: make PR to amend original Workspaces RFC a picture/visual of our terminology w/ glossary
• @fritzy
  • believe our definition is fine so long as we're consistent & glossary is explicit
• Action: Add glossary to npm/cli docs (rough draft)
• Action: editorial pass through existing npm/cli docs to make sure we're using these terms properly
• Action: (nice to have) Automatically link words in docs to their glossary definitions (this might be too noisy/complicated?)