[RRFC] Improving workspace terminology
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 777
- Forks
- 267
- PR merge metrics
- No merged PRs in 30d
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading implemented/0026-workspaces.md, especially its dictionary, examples, summary, and motivation, then compare the terminology with the issue's desired behavior. Done means the RFC consistently distinguishes the outer workspace from its contained packages without changing workspace functionality.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100