From a67c465da21287e1e880882ab8db606dc0b89a15 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 10:44:55 -0500
Subject: [PATCH 1/9] docs(ref): Re-org workspace docs to be like package docs

In looking over #10625, I remembered we've been having growing pains
with the workspace documentation.  It was originally written when there
were a lot fewer workspace features.  As more workspace features have
been added, they've been tacked on to the documentation.

This re-thinks the documentation by focusing on the schema, much like
`manifest.md` does.
---
 src/doc/src/reference/manifest.md             |  4 +-
 src/doc/src/reference/resolver.md             |  2 +-
 .../src/reference/specifying-dependencies.md  |  2 +-
 src/doc/src/reference/unstable.md             |  6 +-
 src/doc/src/reference/workspaces.md           | 99 +++++++++++++------
 5 files changed, 76 insertions(+), 37 deletions(-)

diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index e239042dcfc..cdc1bd1c32a 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -512,7 +512,7 @@ external tools may wish to use them in a consistent fashion, such as referring
 to the data in `workspace.metadata` if data is missing from `package.metadata`,
 if that makes sense for the tool in question.
 
-[workspace-metadata]: workspaces.md#the-workspacemetadata-table
+[workspace-metadata]: workspaces.md#the-metadata-table
 
 #### The `default-run` field
 
@@ -599,7 +599,7 @@ more detail.
         "#the-required-features-field-optional": "cargo-targets.html#the-required-features-field",
         "#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field",
         "#the-workspace-section": "workspaces.html#the-workspace-section",
-        "#virtual-manifest": "workspaces.html",
+        "#virtual-workspace": "workspaces.html",
         "#package-selection": "workspaces.html#package-selection",
         "#the-features-section": "features.html#the-features-section",
         "#rules": "features.html",
diff --git a/src/doc/src/reference/resolver.md b/src/doc/src/reference/resolver.md
index d3476d08366..c66541d4dc1 100644
--- a/src/doc/src/reference/resolver.md
+++ b/src/doc/src/reference/resolver.md
@@ -427,7 +427,7 @@ members = ["member1", "member2"]
 resolver = "2"
 ```
 
-[virtual workspace]: workspaces.md#virtual-manifest
+[virtual workspace]: workspaces.md#virtual-workspace
 [features-2]: features.md#feature-resolver-version-2
 
 ## Recommendations
diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md
index 36ddf0dbb5a..8e3dbf1bc1a 100644
--- a/src/doc/src/reference/specifying-dependencies.md
+++ b/src/doc/src/reference/specifying-dependencies.md
@@ -489,7 +489,7 @@ rand = { workspace = true, optional = true }
 
 [crates.io]: https://crates.io/
 [dev-dependencies]: #development-dependencies
-[workspace.dependencies]: workspaces.md#the-workspacedependencies-table
+[workspace.dependencies]: workspaces.md#the-dependencies-table
 [optional]: features.md#optional-dependencies
 [features]: features.md
 
diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md
index a04c51fdc76..6570a61e52e 100644
--- a/src/doc/src/reference/unstable.md
+++ b/src/doc/src/reference/unstable.md
@@ -1358,7 +1358,7 @@ for more information.
 ### Workspace Inheritance
 
 Workspace Inheritance has been stabilized in the 1.64 release.
-See [workspace.package](workspaces.md#the-workspacepackage-table), 
-[workspace.dependencies](workspaces.md#the-workspacedependencies-table), 
+See [workspace.package](workspaces.md#the-package-table), 
+[workspace.dependencies](workspaces.md#the-dependencies-table), 
 and [inheriting-a-dependency-from-a-workspace](specifying-dependencies.md#inheriting-a-dependency-from-a-workspace)
-for more information.
\ No newline at end of file
+for more information.
diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index bb3872265d1..cc378d2b724 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -3,39 +3,80 @@
 A *workspace* is a collection of one or more packages that share common
 dependency resolution (with a shared `Cargo.lock`), output directory, and
 various settings such as profiles. Packages that are part of a workspaces are
-called *workspace members*. There are two flavours of workspaces: as root
-package or as virtual manifest.
+called *workspace members*.
 
-### Root package
+The key points of workspaces are:
+
+* All packages share a common `Cargo.lock` file which resides in the
+  *workspace root*.
+* All packages share a common [output directory], which defaults to a
+  directory named `target` in the *workspace root*.
+* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
+  sections in `Cargo.toml` are only recognized in the *root* manifest, and
+  ignored in member crates' manifests.
 
-A workspace can be created by adding a [`[workspace]`
-section](#the-workspace-section) to `Cargo.toml`. This can be added to a
-`Cargo.toml` that already defines a `[package]`, in which case the package is
+In the `Cargo.toml`, the `[workspace]` table supports the following sections:
+
+* [`[workspace]`](#the-workspace-section) — Defines a workspace.
+  * [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
+  * [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
+  * [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
+  * [`metadata`](#the-metadata-table) — Extra settings for external tools.
+  * [`package`](#the-package-table) — Keys for inheriting in packages.
+  * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
+
+### The `[workspace]` section
+
+To create a workspace, you add the `[workspace]` table to a `Cargo.toml`:
+```toml
+[workspace]
+# ...
+```
+
+At minimum, a workspace has to have a member, either with a root package or as
+a virtual manifest.
+
+#### Root package
+
+If the [`[workspace]` section](#the-workspace-section) is added to a
+`Cargo.toml` that already defines a `[package]`, the package is
 the *root package* of the workspace. The *workspace root* is the directory
 where the workspace's `Cargo.toml` is located.
 
-### Virtual manifest
+```toml
+[workspace]
+
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0"    # the current version, obeying semver
+authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
+```
+
+<a id="virtual-manifest"></a>
+#### Virtual workspace
 
 Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
 but without a [`[package]` section][package]. This is called a *virtual
 manifest*. This is typically useful when there isn't a "primary" package, or
 you want to keep all the packages organized in separate directories.
 
-### Key features
-
-The key points of workspaces are:
+```toml
+# [PROJECT_DIR]/Cargo.toml
+[workspace]
+members = ["hello_world"]
+```
 
-* All packages share a common `Cargo.lock` file which resides in the
-  *workspace root*.
-* All packages share a common [output directory], which defaults to a
-  directory named `target` in the *workspace root*.
-* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
-  sections in `Cargo.toml` are only recognized in the *root* manifest, and
-  ignored in member crates' manifests.
+```toml
+# [PROJECT_DIR]/hello_world/Cargo.toml
+[package]
+name = "hello_world" # the name of the package
+version = "0.1.0"    # the current version, obeying semver
+authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
+```
 
-### The `[workspace]` section
+### The `members` and `exclude` fields 
 
-The `[workspace]` table in `Cargo.toml` defines which packages are members of
+The `members` and `exclude` fields define which packages are members of
 the workspace:
 
 ```toml
@@ -56,11 +97,6 @@ workspace. This can be useful if some path dependencies aren't desired to be
 in the workspace at all, or using a glob pattern and you want to remove a
 directory.
 
-An empty `[workspace]` table can be used with a `[package]` to conveniently
-create a workspace with the package and all of its path dependencies.
-
-### Workspace selection
-
 When inside a subdirectory within the workspace, Cargo will automatically
 search the parent directories for a `Cargo.toml` file with a `[workspace]`
 definition to determine which workspace to use. The [`package.workspace`]
@@ -68,14 +104,17 @@ manifest key can be used in member crates to point at a workspace's root to
 override this automatic search. The manual setting can be useful if the member
 is not inside a subdirectory of the workspace root.
 
-### Package selection
+#### Package selection
 
 In a workspace, package-related cargo commands like [`cargo build`] can use
 the `-p` / `--package` or `--workspace` command-line flags to determine which
 packages to operate on. If neither of those flags are specified, Cargo will
 use the package in the current working directory. If the current directory is
-a virtual workspace, it will apply to all members (as if `--workspace` were
-specified on the command-line).
+a [virtual workspace](#virtual-workspace), it will apply to all members (as if
+`--workspace` were specified on the command-line).  See also
+[`default-members`](#the-default-members-field).
+
+### The `default-members` field
 
 The optional `default-members` key can be specified to set the members to
 operate on when in the workspace root and the package selection flags are not
@@ -89,7 +128,7 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
 
 When specified, `default-members` must expand to a subset of `members`.
 
-### The `workspace.metadata` table
+### The `metadata` table
 
 The `workspace.metadata` table is ignored by Cargo and will not be warned
 about. This section can be used for tools that would like to store workspace
@@ -112,7 +151,7 @@ external tools may wish to use them in a consistent fashion, such as referring
 to the data in `workspace.metadata` if data is missing from `package.metadata`,
 if that makes sense for the tool in question.
 
-### The `workspace.package` table
+### The `package` table
 
 The `workspace.package` table is where you define keys that can be
 inherited by members of a workspace. These keys can be inherited by
@@ -157,7 +196,7 @@ description.workspace = true
 documentation.workspace = true
 ```
 
-### The `workspace.dependencies` table
+### The `dependencies` table
 
 The `workspace.dependencies` table is where you define dependencies to be
 inherited by members of a workspace.

From c0da05502a0c924ed0f15518e6e0f75a8ec1be89 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 10:48:30 -0500
Subject: [PATCH 2/9] docs(ref): Have workspace docs link out to resolver field
 docs

This is a part of the schema we were missing.  A first step before
encouraging people to use it is to document it!
---
 src/doc/src/reference/workspaces.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index cc378d2b724..db7f050b3c1 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -18,6 +18,7 @@ The key points of workspaces are:
 In the `Cargo.toml`, the `[workspace]` table supports the following sections:
 
 * [`[workspace]`](#the-workspace-section) — Defines a workspace.
+  * [`resolver`](resolver.md#resolver-versions) — Sets the dependency resolver to use.
   * [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
   * [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
   * [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.

From 10c3bea79412fad1278fbb4491c8d2aa29211d81 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 10:52:34 -0500
Subject: [PATCH 3/9] docs(ref): Have workspace docs link out to profile
 section docs

In a workspace, only the workspace's profile is respected.  This is
already documented in the profile documentation but we should raise
visibility of it within the workspace documentation.
---
 src/doc/src/reference/workspaces.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index db7f050b3c1..ec351bbb6c1 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -25,6 +25,7 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections:
   * [`metadata`](#the-metadata-table) — Extra settings for external tools.
   * [`package`](#the-package-table) — Keys for inheriting in packages.
   * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
+* [`[profile]`](profiles.md) — Compiler settings and optimizations.
 
 ### The `[workspace]` section
 

From 7962dae3988eed1b29815871a3a7f3e5a0f699f9 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 11:01:04 -0500
Subject: [PATCH 4/9] docs(ref): Have workspace docs link out to patch/replace
 docs

The workspace behavior doesn't seem to be documented at all, so a blurb
was brought in that is like the profile blurb.  The workspace docs then
link out to it so users can be aware of this special workspace behavior.
---
 src/doc/src/reference/overriding-dependencies.md | 8 ++++++++
 src/doc/src/reference/workspaces.md              | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md
index 504811d5bba..d3e2fa42af1 100644
--- a/src/doc/src/reference/overriding-dependencies.md
+++ b/src/doc/src/reference/overriding-dependencies.md
@@ -291,6 +291,10 @@ also be patched with versions of crates that already exist. If a source is
 patched with a crate version that already exists in the source, then the
 source's original crate is replaced.
 
+Cargo only looks at the patch settings in the `Cargo.toml` manifest at the
+root of the workspace. Patch settings defined in dependencies will be
+ignored.
+
 ### The `[replace]` section
 
 > **Note**: `[replace]` is deprecated. You should use the
@@ -313,6 +317,10 @@ dependencies, except that you can't specify features. Note that when a crate
 is overridden the copy it's overridden with must have both the same name and
 version, but it can come from a different source (e.g., git or a local path).
 
+Cargo only looks at the replace settings in the `Cargo.toml` manifest at the
+root of the workspace. Replace settings defined in dependencies will be
+ignored.
+
 ### `paths` overrides
 
 Sometimes you're only temporarily working on a crate and you don't want to have
diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index ec351bbb6c1..b0164e9a455 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -25,6 +25,8 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections:
   * [`metadata`](#the-metadata-table) — Extra settings for external tools.
   * [`package`](#the-package-table) — Keys for inheriting in packages.
   * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
+* [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies.
+* [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated).
 * [`[profile]`](profiles.md) — Compiler settings and optimizations.
 
 ### The `[workspace]` section

From cfd1c7eb4a5cfd1a1c62de35b507865eb2972a64 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 12:02:11 -0500
Subject: [PATCH 5/9] docs(ref): Move metadata to last

---
 src/doc/src/reference/workspaces.md | 48 ++++++++++++++---------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index b0164e9a455..0d764a5c569 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -22,9 +22,9 @@ In the `Cargo.toml`, the `[workspace]` table supports the following sections:
   * [`members`](#the-members-and-exclude-fields) — Packages to include in the workspace.
   * [`exclude`](#the-members-and-exclude-fields) — Packages to exclude from the workspace.
   * [`default-members`](#the-default-members-field) — Packages to operate on when a specific package wasn't selected.
-  * [`metadata`](#the-metadata-table) — Extra settings for external tools.
   * [`package`](#the-package-table) — Keys for inheriting in packages.
   * [`dependencies`](#the-dependencies-table) — Keys for inheriting in package dependencies.
+  * [`metadata`](#the-metadata-table) — Extra settings for external tools.
 * [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies.
 * [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated).
 * [`[profile]`](profiles.md) — Compiler settings and optimizations.
@@ -132,29 +132,6 @@ default-members = ["path/to/member2", "path/to/member3/foo"]
 
 When specified, `default-members` must expand to a subset of `members`.
 
-### The `metadata` table
-
-The `workspace.metadata` table is ignored by Cargo and will not be warned
-about. This section can be used for tools that would like to store workspace
-configuration in `Cargo.toml`. For example:
-
-```toml
-[workspace]
-members = ["member1", "member2"]
-
-[workspace.metadata.webcontents]
-root = "path/to/webproject"
-tool = ["npm", "run", "build"]
-# ...
-```
-
-There is a similar set of tables at the package level at
-[`package.metadata`][package-metadata]. While cargo does not specify a
-format for the content of either of these tables, it is suggested that
-external tools may wish to use them in a consistent fashion, such as referring
-to the data in `workspace.metadata` if data is missing from `package.metadata`,
-if that makes sense for the tool in question.
-
 ### The `package` table
 
 The `workspace.package` table is where you define keys that can be
@@ -239,6 +216,29 @@ cc.workspace = true
 rand.workspace = true
 ```
 
+### The `metadata` table
+
+The `workspace.metadata` table is ignored by Cargo and will not be warned
+about. This section can be used for tools that would like to store workspace
+configuration in `Cargo.toml`. For example:
+
+```toml
+[workspace]
+members = ["member1", "member2"]
+
+[workspace.metadata.webcontents]
+root = "path/to/webproject"
+tool = ["npm", "run", "build"]
+# ...
+```
+
+There is a similar set of tables at the package level at
+[`package.metadata`][package-metadata]. While cargo does not specify a
+format for the content of either of these tables, it is suggested that
+external tools may wish to use them in a consistent fashion, such as referring
+to the data in `workspace.metadata` if data is missing from `package.metadata`,
+if that makes sense for the tool in question.
+
 [package]: manifest.md#the-package-section
 [package-metadata]: manifest.md#the-metadata-table
 [output directory]: ../guide/build-cache.md

From 5b950a3ecf9b8cad857361b81b4b92fd6bdbdafb Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 14:03:02 -0500
Subject: [PATCH 6/9] docs(ref): Remove redundant workspace description

---
 src/doc/src/reference/workspaces.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index 0d764a5c569..376c3226de8 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -1,9 +1,7 @@
 ## Workspaces
 
-A *workspace* is a collection of one or more packages that share common
-dependency resolution (with a shared `Cargo.lock`), output directory, and
-various settings such as profiles. Packages that are part of a workspaces are
-called *workspace members*.
+A *workspace* is a collection of one or more packages, called *workspace
+members*, that are managed together.
 
 The key points of workspaces are:
 

From 2bcf1a70b4fe1f8d620c7638a9da53e5798f1091 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 14:04:59 -0500
Subject: [PATCH 7/9] docs(ref): Add --workspace as a key point

This is a frequent reason I use them
---
 src/doc/src/reference/workspaces.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index 376c3226de8..4a234b884f0 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -5,6 +5,7 @@ members*, that are managed together.
 
 The key points of workspaces are:
 
+* Common commands can run across all workspace members, like `cargo check --workspace`.
 * All packages share a common `Cargo.lock` file which resides in the
   *workspace root*.
 * All packages share a common [output directory], which defaults to a

From 7997f1e9cf4b4e8a582d559a77744ec36a5e4ed5 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 14:06:17 -0500
Subject: [PATCH 8/9] docs(ref): Include workspace inheritane

---
 src/doc/src/reference/workspaces.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index 4a234b884f0..867596bedf7 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -10,6 +10,7 @@ The key points of workspaces are:
   *workspace root*.
 * All packages share a common [output directory], which defaults to a
   directory named `target` in the *workspace root*.
+* Sharing package metadata, like with [`workspace.package`](#the-package-table).
 * The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
   sections in `Cargo.toml` are only recognized in the *root* manifest, and
   ignored in member crates' manifests.

From a1c48c56fe5c2dfa98ad35d479fd5496413dcf94 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Tue, 13 Sep 2022 14:08:01 -0500
Subject: [PATCH 9/9] docs(ref): Provide path for people to finding why shared
 Cargo.lock matters

---
 src/doc/src/reference/workspaces.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
index 867596bedf7..03e7b02ff23 100644
--- a/src/doc/src/reference/workspaces.md
+++ b/src/doc/src/reference/workspaces.md
@@ -6,7 +6,7 @@ members*, that are managed together.
 The key points of workspaces are:
 
 * Common commands can run across all workspace members, like `cargo check --workspace`.
-* All packages share a common `Cargo.lock` file which resides in the
+* All packages share a common [`Cargo.lock`] file which resides in the
   *workspace root*.
 * All packages share a common [output directory], which defaults to a
   directory named `target` in the *workspace root*.
@@ -240,6 +240,7 @@ to the data in `workspace.metadata` if data is missing from `package.metadata`,
 if that makes sense for the tool in question.
 
 [package]: manifest.md#the-package-section
+[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md
 [package-metadata]: manifest.md#the-metadata-table
 [output directory]: ../guide/build-cache.md
 [patch]: overriding-dependencies.md#the-patch-section