Workspace naming is confusing

[jasonwilliams]

I may be missing something obvious, but why aren't packages within a workspace defined as such? There are contradictions among the documentation which interchanges between packages and workspaces.
RFC: https://github.com/npm/rfcs/blob/latest/implemented/0026-workspaces.md

First off for me a workspace is the top-level folder which holds all of the packages that you work in. But the inner packages 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?

But 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.

Notes
npm/rfcs#103

[arcanis]

First off for me a workspace is the top-level folder which holds all of the packages that you work in. But the inner packages which can be published to npm are packages.

Fwiw that's not the case in Yarn, which is perhaps the main way the JS ecosystem is exposed to workspaces. To quote the nomenclature from our documentation:

First, some vocabulary: in the context of the workspace feature, a project is the whole directory tree making up your workspaces (often the repository itself). A workspace is a specific named package stored anywhere within the project. Finally, a worktree is the name given to packages that list their own child workspaces. A project contains one or more worktrees, which may themselves contain any number of workspaces.

I would discourage you from deviating from this definition if you intend to keep the workspaces property to define your workspaces, as it would be needlessly confusing for everyone. If you want to change it, you can do what pnpm did and use a different definition syntax.

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

This is one article, versus years of consistent usage. Articles can make mistakes too.

[arcanis]

Breaking change is a thing in terms of terminology too. Quoting my previous comment:

If you use the same, people writing articles about our syntax will have no way to write them in a way that's understandable by both package manager users, leading to a largely avoidable confusion depending on whether the articles / tutorials got written by a Yarn or npm user.

If I say that blue is now red, all articles / tutorials / support threads referring to red prior the change now don't make any sense.

[jasonwilliams]

Hey @arcanis thanks, I’m aware breaking changes should include documentation (I write a lot of APIs and docs myself).
However here I’m referring to the RFC itself in response to @MylesBorins statement that “this has shipped”, no new code needs to be shipped in a new version to accommodate these changes.

If I say that blue is now red, all articles / tutorials / support threads referring to red prior the change now don't make any sense.

Well as both me and @ljharb pointed out, this is a new feature, it’s better to address issues now before the problem gets worse for millions later. I don’t want to repeat everything that’s being said above but not doing anything will cause just as many problems (probably more) than doing something.

[ljharb]

This confusion comes up in literally every RFC call that discusses workspaces, as well as in almost every issue/PR about it. Sometimes when people say "workspace" they mean a child project, and sometimes they mean the repo itself. We've been dancing around it by using terms like "parent workspace" or "child workspace", but clarifying the terms will help not just in docs, but also so discussion about the feature uses more universally shared terminology.

[MylesBorins]

I may have misunderstood and assumed that this suggested change would have involved changes to the manifest / configuration, not only to definitions + documentation.

Either way I do think it is worth opening an RFC to discuss the larger change.

[isaacs]

Was going to reply here, but it got too long. #510 (comment)

tl;dr - I agree with @arcanis and I think npm should continue trying to match yarn's definitions.

[isaacs]

Naming things is hard. Human language is a slippery beast at best. (This is similar to the module/package/dependency semantic rats' nest, and occasionally gets entangled with it.)

We have been trying to converge on this terminology, which I believe is compatible with Yarn's semantics:

• project or project root - The parent directory where you run npm commands, which has a package.json, and is typically the root of the git repository. This may include a workspaces definition in its package.json file. This may be a published package, or just a parent of workspaces that does not define any other functionality of its own. If it defines workspaces in package.json, then you may use npm commands with the --workspace=<name> or --workspaces options.
• workspace or child workspace - The thing that is referenced by workspaces in the project.
• workspace root - A project root that includes a workspaces definition.
• package - A thing that can be operated on by npm and referenced by a package specifier. A tarball file or url, name@spec, a folder path containing a package.json, etc.
• manifest - A set of metadata describing a package, typically written in package.json, but also served by the registry, loaded from a lockfile, etc.
• dependency
  1. A stated requirement of a package, listed in dependencies, devDependencies, etc. of a manifest.
  2. A package satisfies a dependency(1). Typically, a folder in node_modules, but may also be an abstract representation of a package in a manifest.
• packument - A document describing all published versions of a package with a given name, including their dist-tags, manifests, and other metadata.
• module - A thing that may be loaded by the require() or import functions in JavaScript. A package is typically a module if it includes a main field in its manifest, or if it contains an index.js file.
• specifier - A representation of a dependency(1), which may include the name of the dependency, either as a string (such as [email protected]) or a parsed representation of it.

Within npm's internals (particularly Arborist), we also have the following more technical definitions:

• node - An abstract representation of a package in a dependency graph, which may be reified to or loaded from either the file system or a lockfile.
• link - An abstract representation of a symbolic link to a node.
• edge - An abstract representation of a dependency(1), including the node with the dependency, the type and specifier defining it, the link or node that it will resolve to (if any), and the error state if the dependency represented is not properly met.
• workspace - (more precisely than above) A node that is included in the workspaces definition of a project, or a link to a workspace node.
• root - The node representing the project root.

npm does not (yet?) have a concept of "worktrees".

I do not personally have any strong opinion on how these terms are defined, but I am very much in agreement with @arcanis that it's valuable to have npm and yarn be in sync here. Since yarn implemented workspaces a few years ahead of npm, yarn has set the definitions, and that's fine. Changing them now seems like it would not be worthwhile.

I am willing to bet that some of npm's documentation is currently using these terms imprecisely or even incorrectly. Those cases are documentation bugs that should be fixed.

I do realize that lerna predates yarn, and yarn deviated from lerna's naming conventions. But (a) npm is more like yarn than it is like lerna, and (b) we have to pick one to follow, and we picked yarn, and here we are. Picking lerna's definitions instead would have also been fine, but it's not how it went.