chore: docs improvements

core/lerna/commands/add-caching/README.md

@@ -14,7 +14,7 @@ $ lerna add-caching
 
 Each question the wizard asks will inform how the `nx.json` file is updated.
 
-### Which of the following scripts need to be run in deterministic/topological order?
+### Which scripts need to be run in order?
 
 Each script selected will be marked to run dependency scripts of the same name before running the script itself.
 
@@ -32,7 +32,7 @@ If you mark `build` as needing topological order, the `nx.json` file will look l
 }
 ```
 
-### Which of the following scripts are cacheable?
+### Which scripts are cacheable?
 
 Each script selected will be cached by Lerna.  Only select scripts that do not depend on any external inputs (like network calls).  `build` and `test` are usually cacheable.  `start` and `serve` are usually not cacheable.  Sometimes `e2e` is cacheable.
 

website/docs/concepts/alternate-bootstrapping-methods.md

@@ -1,12 +1,18 @@
 ---
 id: alternate-bootstrapping-methods
-title: Alternate Bootstrapping Methods
+title: "Legacy: Alternate Bootstrapping Methods"
 type: explainer
 ---
 
-# Alternate Bootstrapping Methods
+# Legacy: Alternate Bootstrapping Methods
 
-If you can't [use your package manager's built in bootstrapping support](../features/bootstrap) for some reason, Lerna can handle the bootstrapping for you. There are several ways Lerna can set up your monorepo such that an app (`remixapp`) can find libraries in the same repo (`header` and `footer`), and one of them is to make it such that the `header` and `footer` end up in the `node_modules` folder of `remixapp` (or a different folder at the root)--that's what `lerna bootstrap` (without `--use-workspaces`) does.
+:::info
+
+NOTE: Lerna's legacy package management capabilities are being deprecated in Lerna v7, [please see here for full background](../features/legacy-package-management)
+
+:::
+
+There are several ways Lerna can set up your monorepo such that an app (`remixapp`) can find libraries in the same repo (`header` and `footer`), and one of them is to make it such that the `header` and `footer` end up in the `node_modules` folder of `remixapp` (or a different folder at the root)--that's what `lerna bootstrap` (without `--use-workspaces`) does.
 
 Running `lerna bootstrap` will invoke `npm install` in each of the packages, and will link local package such that the resulting structure will look like this.
 

website/docs/concepts/hoisting.md

@@ -1,10 +1,17 @@
 ---
 id: hoisting
-title: Hoisting
+title: "Legacy: Hoisting"
 type: explainer
 ---
 
-# Hoisting
+# Legacy: Hoisting
+
+:::info
+
+NOTE: Lerna's legacy package management capabilities are being deprecated in Lerna v7, [please see here for full background](../features/legacy-package-management)
+
+:::
+
 
 ```bash
 lerna bootstrap --hoist

website/docs/features/legacy-package-management.md

@@ -0,0 +1,95 @@
+---
+id: legacy-package-management
+title: Legacy Package Management
+type: recipe
+---
+
+# Legacy Package Management
+
+## Background
+
+Lerna is the original monorepo/workspace tool in the JavaScript ecosystem. When it was created in 2015/2016 the ecosystem looked totally different, and there were no built in capabilities to handle working with multiple packages in a single repository (a "workspace"). Commands like lerna bootstrap, lerna add and lerna link were all a critical part of the lerna project, because there were no other options.
+
+However, now that we find ourselves in late 2022, the fact is that - for many years now - the package managers we know and love (`npm`, `yarn` and `pnpm`) all fully support that concept of workspaces as a first-class use-case.
+
+They have battle tested implementations covering adding, removing and linking local packages, and combining them with third party dependencies in a natural way.
+
+This is the reason why, for the past several years of his tenure as lead maintainer of Lerna, Daniel, has been encouraging folks to strongly reconsider their use of the legacy package management commands in lerna, and instead leverage their package manager of choice to do what it does best.
+
+We knew about this context from afar, but as new stewards of the project we did not want to jump straight in and start removing capabilities without first taking the time to get familiar with the reality up close. Now that we have been actively maintaining the project for half a year, we are in full agreement with Daniel and others that the legacy package management commands in lerna need to be retired.
+
+By removing these legacy pieces which have better alternatives natively in package managers, we and the rest of the lerna community will be freed up to concentrate our efforts on things which are uniquely valuable about lerna (such as, but not limited to, versioning and publishing), and making them the best they can be!
+
+From version 7, therefore, we will no longer ship the legacy package management commands (such as lerna bootstrap, lerna add and lerna link) by default with lerna, and instead make them available as an add-on via a separate package (name TBD).
+
+This new package can be thought of as being in maintenance mode only - no new features will be considered for legacy package management concerns (such as lerna bootstrap, lerna add and lerna link), and we will only look to merge critical patches and security updates.
+
+:::info
+
+This same context is covered on the [Lerna v7 discussion](https://github.com/lerna/lerna/discussions/3410), if you have any specific concerns, please join us there and provide as much information as possible!
+
+:::
+
+## Legacy Bootstrap Command
+
+Lerna's legacy bootstrap command links different projects within the repo so they can import each other without having to publish anything to NPM. To show how Lerna does it, we will take [this repository](https://github.com/lerna/getting-started-example) as an example.
+
+The repo contains three packages or projects:
+
+- `header` (a library of React components)
+- `footer` (a library of React components)
+- `remixapp` (an app written using the Remix framework which depends on both `header` and `footer`)
+
+The Remix app imports the `header` and `footer` libraries as follows:
+
+```typescript jsx title="packages/remixapp/app/routes/index.tsx"
+import { Header } from "header";
+import { Footer } from "footer";
+
+export default function Index() {
+  return (
+    <>
+      <Header />
+      <div>Content!</div>
+      <Footer />
+    </>
+  );
+}
+```
+
+And it depends on them in its `package.json` as follows:
+
+```json title="packages/remixapp/package.json"
+{
+  "dependencies": {
+    "@remix-run/node": "^1.5.1",
+    "@remix-run/react": "^1.5.1",
+    "@remix-run/serve": "^1.5.1",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "header": "*",
+    "footer": "*"
+  }
+}
+```
+
+To make the `header` and `footer` available inside the `remixapp`, run:
+
+```bash
+lerna bootstrap --use-workspaces
+```
+
+This installs all the dependencies needed for the 3 projects and links the `header` and `footer` projects so that `remixapp` can reference them like npm packages. `--use-workspaces` tells Lerna to delegate package linking process to your package manager. (This feature is supported by npm, yarn and pnpm.)
+
+You can also set `useWorkspaces` as the default behavior in the `lerna.json` file:
+
+```json title="lerna.json"
+{
+    ...
+    "useWorkspaces": true
+}
+```
+
+## Other Bootstrapping Methods
+
+Bootstrapping this way should work for most people, but you can use [Alternate Legacy Bootstrapping Methods](../concepts/alternate-bootstrapping-methods) if needed.

website/docs/getting-started.md

@@ -91,7 +91,7 @@ When running `lerna init`, Lerna configures the workspace to use NPM/YARN/PNPM w
 
 :::info
 
-Lerna has its own dependency management solution: `lerna bootstrap`. This was required because at the times when Lerna got first released, there were no solutions available. Nowadays the modern package managers come with a built-in "workspaces" solution, so it is highly recommended to go with that instead.
+Lerna has historically its own dependency management solution: `lerna bootstrap`. This was required because at the time when Lerna was first released, there were no native solutions available. Nowadays the modern package managers come with a built-in "workspaces" solution, so it is highly recommended to go with that instead. `lerna bootstrap` and other related commands will be officially deprecated in Lerna v7. See https://github.com/lerna/lerna/discussions/3410
 :::
 
 You can see this configured in the root-level `package.json` `workspaces` property as well as by having `useWorkspaces` set to `true` in `lerna.json`
@@ -128,7 +128,7 @@ npm install
 
 Now all the projects in the workspace can properly reference each other via local package linking.
 
-## Visualizing Workspace
+## Visualizing the Workspace
 
 Since Lerna is powered by Nx, you can use its capabilities to open an interactive visualization of the workspace project graph.
 
@@ -200,7 +200,7 @@ npx lerna add-caching
 A series of questions will be asked to properly configure the workspace:
 
 ```bash
-? Which of the following scripts need to be run in deterministic/topoglogical order?
+? Which scripts need to be run in order? (e.g. before building a project, dependent projects must be built.)
  (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
 ❯◉ build
  ◯ test
@@ -209,8 +209,7 @@ A series of questions will be asked to properly configure the workspace:
 ```
 
 ```bash
-? Which of the following scripts are cacheable? (Produce the same output given the same input, e.g. build, test and lint usually are, serve and
-start are not)
+? Which scripts are cacheable? (Produce the same output given the same input, e.g. build, test and lint usually are, serve and start are not.)
  (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
  ◉ build
 ❯◉ test

website/docs/introduction.md

@@ -14,11 +14,11 @@ It solves three of the biggest problems of JavaScript monorepos:
 - Lerna runs a command against any number of projects, and it does it in the most efficient way, in the right order, and with the possibility to distribute that on multiple machines.
 - Lerna manages your publishing process, from version management to publishing to NPM, and it provides a variety of options to make sure any workflow can be accommodated.
 
-Nrwl (the company behind the open source build system Nx) has taken over [stewardship of Lerna](https://dev.to/nrwl/lerna-is-dead-long-live-lerna-3jal). [Nx](https://nx.dev) is a build system developed by ex-Googlers and utilizes many of the techniques used by internal Google tools. Lerna v5 is the first release under this new stewardship, updating outdated packages and starting to do some cleanup on the repository itself. Starting with v5.1+, Lerna comes with the new possibility to integrate Nx and defer a lot of the task scheduling work to it.
+Nrwl (the company behind the open source build system Nx) has taken over [stewardship of Lerna](https://dev.to/nrwl/lerna-is-dead-long-live-lerna-3jal). [Nx](https://nx.dev) is a build system developed by ex-Googlers and utilizes many of the techniques used by internal Google tools. Lerna v5 is the first release under this new stewardship, updating outdated packages and starting to do some cleanup on the repository itself. Starting with v6+, Lerna delegates task scheduling work to Nx's battle tested, industry-leading task runner, meaning `lerna run` gets the benefits of caching and command distribution for free!
 
 ## Why Lerna?
 
-- **Super Fast!** Lerna v5+ is fast, even faster than most comparable solutions out there ([see this benchmark](https://github.com/vsavkin/large-monorepo) to learn more). How? Under the hood, [Lerna v5+ has the ability to use Nx to run tasks](https://twitter.com/i/status/1529493314621145090). Learn more about [running tasks here](./features/run-tasks.md).
+- **Super Fast!** Lerna is fast, even faster than most comparable solutions out there ([see this benchmark](https://github.com/vsavkin/large-monorepo) to learn more). How? Under the hood, [Lerna v6+ uses Nx to run tasks](https://twitter.com/i/status/1529493314621145090). Learn more about [running tasks here](./features/run-tasks.md).
 - **Computation Caching** - Lerna knows when the task you are about to run has been executed in the past. Instead of running it, Lerna will restore the files and replay the terminal output instantly. Plus, this cache can be shared with your co-workers and CI. When using Lerna, your whole organization will never have to build or test the same thing twice. [Read more »](./features/cache-tasks.md)
 - **Configuration-Free Distributed Task Execution** Lerna can distribute any command across multiple machines without any configuration, while preserving the dev ergonomics of running it on a single machine. In other words, scaling your monorepo with Lerna is as simple as enabling a boolean flag. See the examples of how enabling DTE can make you CI 20 times faster. [Read more »](./features/distribute-tasks.md)
 - **Beautiful Terminal Output** Monorepos can have hundreds or thousands of projects. Printing everything on every command makes it hard to see what fails and why. Thankfully, Lerna does a much better job.

website/docs/lerna-and-nx.md

@@ -14,9 +14,8 @@ The following is a high level overview of what each tool provides. Note that all
 
 ### Features
 
-1. [Bootstrap](./features/bootstrap) - Link packages together in the same repo so they can be imported as if they were installed from NPM.
-2. [Version](./features/version-and-publish) - Automatically increment versions of packages
-3. [Publish](./features/version-and-publish) - Automatically create tags and publish packages
+1. [Version](./features/version-and-publish) - Automatically increment versions of packages, generate changelog information, create Github releases etc.
+2. [Publish](./features/version-and-publish) - Automatically create tags and publish packages to package registries, such as npm
 
 ### Cost
 

website/sidebars.js

@@ -25,14 +25,14 @@ const sidebars = {
       type: "category",
       label: "Features",
       items: [
-        "features/bootstrap",
         "features/run-tasks",
         "features/cache-tasks",
         "features/share-your-cache",
         "features/project-graph",
         "features/distribute-tasks",
         "features/version-and-publish",
         "features/editor-integrations",
+        "features/legacy-package-management",
       ],
       link: {
         type: "generated-index",
@@ -45,11 +45,11 @@ const sidebars = {
       type: "category",
       label: "Concepts",
       items: [
-        "concepts/alternate-bootstrapping-methods",
-        "concepts/hoisting",
         "concepts/task-pipeline-configuration",
         "concepts/how-caching-works",
         "concepts/dte-guide",
+        "concepts/alternate-bootstrapping-methods",
+        "concepts/hoisting",
       ],
       link: {
         type: "generated-index",