docs(ref): Clarify workspace settings #11082

epage · 2022-09-13T16:09:28Z

What does this PR try to resolve?

In reviewing the status of #10625, I was reminded

that we are having growing pains with the workspace documentation
that workspace.resolver isn't documented

So I re-organized the workspace docs to have a high level intro / behavior description and then to focus on being a field reference, much like manifest.md. I could see splitting it specifically into tutorial/reference like the overriding dependencies document does it.

When adding workspace.resolver, I remembered in the nested workspace discussion there were other workspace related sections that are not present. We now link out to profile, patch, and replace. In doing this, I realized that patch and replace do not specify their workspace behavior, so I do that.

How should we test and review this PR?

Look at it commit by commit to get more digestible chunks. Unfortunately, the first commit didn't split up so easily.

Additional information

Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->

In looking over rust-lang#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.

This is a part of the schema we were missing. A first step before encouraging people to use it is to document it!

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.

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.

rust-highfive · 2022-09-13T16:09:33Z

r? @weihanglo

(rust-highfive has picked a reviewer for you, use r? to override)

Muscraft

The changes make it much easier to read!

src/doc/src/reference/overriding-dependencies.md

src/doc/src/reference/workspaces.md

Muscraft · 2022-09-13T18:18:57Z

src/doc/src/reference/workspaces.md

+* 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*.


Should the benefits of sharing a Cargo.lock and one target dir be explained?

For output, let's rely on the information in that link. For cargo.lock, let's mirror output and provide a link for more details.

src/doc/src/reference/overriding-dependencies.md

This is a frequent reason I use them

…atters

weihanglo

This link needs an update as well.

cargo/src/doc/src/reference/resolver.md

Line 431 in aaadab6

[virtual workspace]: workspaces.md#virtual-manifest

src/doc/src/reference/workspaces.md

weihanglo · 2022-09-16T09:28:18Z

It seems good if we can ship this doc enhancement in 1.64. Should we send a PR to beta as well?

src/doc/src/reference/workspaces.md

weihanglo · 2022-09-16T15:35:04Z

Thank you!

@bors r+

bors · 2022-09-16T15:35:06Z

📌 Commit f39f8dc has been approved by weihanglo

It is now in the queue for this repository.

bors · 2022-09-16T15:35:13Z

⌛ Testing commit f39f8dc with merge 362ce33...

bors · 2022-09-16T16:21:45Z

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing 362ce33 to master...

Beta backport #11082

3 commits in 4bcb3c65e440a12044092b85ffea8fac6cb96f42..387270bc7f446d17869c7f208207c73231d6a252 2022-08-17 21:01:34 +0000 to 2022-09-16 20:18:27 +0000 - Beta backport rust-lang/cargo#11082 (rust-lang/cargo#11097) - [Beta] Run `reach_max_unpack_size` test only on debug build (rust-lang/cargo#11090) - [beta] Fix for CVE-2022-36113 and CVE-2022-36114 (rust-lang/cargo#11088)

8 commits in 082503982ea0fb7a8fd72210427d43a2e2128a63..73ba3f35e0205844418260722c11602113179c4a 2022-09-13 17:49:38 +0000 to 2022-09-18 06:38:16 +0000 - Revert "Clarify when cargo detects changes" (rust-lang/cargo#11107) - Fix links to workspace inheritance headings in workspace docs (rust-lang/cargo#11103) - docs(ref): Clarify workspace settings (rust-lang/cargo#11082) - Update comment about ResolveVersion default version (rust-lang/cargo#11095) - [master] Run `reach_max_unpack_size` test only on debug build (rust-lang/cargo#11091) - Clarify when cargo detects changes (rust-lang/cargo#11092) - [master] Fix for CVE-2022-36113 and CVE-2022-36114 (rust-lang/cargo#11089) - Expose cargo add internals as edit API (rust-lang/cargo#11059)

3 commits in 4bcb3c65e440a12044092b85ffea8fac6cb96f42..387270bc7f446d17869c7f208207c73231d6a252 2022-08-17 21:01:34 +0000 to 2022-09-16 20:18:27 +0000 - Beta backport rust-lang/cargo#11082 (rust-lang/cargo#11097) - [Beta] Run `reach_max_unpack_size` test only on debug build (rust-lang/cargo#11090) - [beta] Fix for CVE-2022-36113 and CVE-2022-36114 (rust-lang/cargo#11088)

Update cargo (CVE fixes included) 8 commits in 082503982ea0fb7a8fd72210427d43a2e2128a63..73ba3f35e0205844418260722c11602113179c4a 2022-09-13 17:49:38 +0000 to 2022-09-18 06:38:16 +0000 - Revert "Clarify when cargo detects changes" (rust-lang/cargo#11107) - Fix links to workspace inheritance headings in workspace docs (rust-lang/cargo#11103) - docs(ref): Clarify workspace settings (rust-lang/cargo#11082) - Update comment about ResolveVersion default version (rust-lang/cargo#11095) - [master] Run `reach_max_unpack_size` test only on debug build (rust-lang/cargo#11091) - Clarify when cargo detects changes (rust-lang/cargo#11092) - [master] Fix for GHSA-rfj2-q3h3-hm5j and GHSA-2hvr-h6gw-qrxp (rust-lang/cargo#11089) - Expose cargo add internals as edit API (rust-lang/cargo#11059)

epage added 4 commits September 13, 2022 11:03

docs(ref): Have workspace docs link out to resolver field docs

5189a81

This is a part of the schema we were missing. A first step before encouraging people to use it is to document it!

docs(ref): Have workspace docs link out to profile section docs

a841274

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.

docs(ref): Have workspace docs link out to patch/replace docs

fb510f5

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.

rust-highfive assigned weihanglo Sep 13, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Sep 13, 2022

epage force-pushed the workspace branch from bd72af8 to 03cc059 Compare September 13, 2022 16:18

Muscraft reviewed Sep 13, 2022

View reviewed changes

src/doc/src/reference/overriding-dependencies.md Show resolved Hide resolved

src/doc/src/reference/workspaces.md Outdated Show resolved Hide resolved

docs(ref): Move metadata to last

0e09e5c

Muscraft reviewed Sep 13, 2022

View reviewed changes

epage force-pushed the workspace branch from e5d822a to 2f6357f Compare September 13, 2022 18:58

epage added 3 commits September 13, 2022 14:03

docs(ref): Remove redundant workspace description

c08ecbb

docs(ref): Add --workspace as a key point

f1da8c4

This is a frequent reason I use them

docs(ref): Include workspace inheritane

cad833d

epage force-pushed the workspace branch from 2f6357f to e349fcd Compare September 13, 2022 19:06

docs(ref): Provide path for people to finding why shared Cargo.lock m…

f39f8dc

…atters

weihanglo added A-documenting-cargo-itself Area: Cargo's documentation A-workspaces Area: workspaces labels Sep 13, 2022

weihanglo reviewed Sep 15, 2022

View reviewed changes

src/doc/src/reference/workspaces.md Outdated Show resolved Hide resolved

src/doc/src/reference/workspaces.md Outdated Show resolved Hide resolved

epage force-pushed the workspace branch 2 times, most recently from 4411d28 to 4ea5dce Compare September 16, 2022 14:26

weihanglo reviewed Sep 16, 2022

View reviewed changes

src/doc/src/reference/workspaces.md Show resolved Hide resolved

epage force-pushed the workspace branch from 4ea5dce to f39f8dc Compare September 16, 2022 15:15

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 16, 2022

bors merged commit 362ce33 into rust-lang:master Sep 16, 2022

bors mentioned this pull request Sep 16, 2022

Add "resolver = 2" option to workspace manifest examples #10625

Closed

epage deleted the workspace branch September 16, 2022 16:33

weihanglo mentioned this pull request Sep 16, 2022

Beta backport #11082 #11097

Merged

weihanglo mentioned this pull request Sep 16, 2022

Update cargo (CVE fixes included) rust-lang/rust#101909

Merged

bors added a commit that referenced this pull request Sep 16, 2022

Auto merge of #11097 - weihanglo:beta-backport-workspace-doc, r=epage

387270b

Beta backport #11082

This was referenced Sep 16, 2022

[beta] Update cargo (CVE fixes included) rust-lang/rust#101922

Closed

Fix links to workspace inheritance headings in workspace docs #11103

Merged

ehuss added this to the 1.65.0 milestone Sep 21, 2022

epage mentioned this pull request Jul 21, 2023

docs: raise awareness of resolver used inside workspace #12388

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(ref): Clarify workspace settings #11082

docs(ref): Clarify workspace settings #11082

epage commented Sep 13, 2022

rust-highfive commented Sep 13, 2022

Muscraft left a comment

Muscraft Sep 13, 2022

epage Sep 13, 2022

weihanglo left a comment

weihanglo commented Sep 16, 2022

weihanglo commented Sep 16, 2022

bors commented Sep 16, 2022

bors commented Sep 16, 2022

bors commented Sep 16, 2022

docs(ref): Clarify workspace settings #11082

docs(ref): Clarify workspace settings #11082

Conversation

epage commented Sep 13, 2022

What does this PR try to resolve?

How should we test and review this PR?

Additional information

rust-highfive commented Sep 13, 2022

Muscraft left a comment

Choose a reason for hiding this comment

Muscraft Sep 13, 2022

Choose a reason for hiding this comment

epage Sep 13, 2022

Choose a reason for hiding this comment

weihanglo left a comment

Choose a reason for hiding this comment

weihanglo commented Sep 16, 2022

weihanglo commented Sep 16, 2022

bors commented Sep 16, 2022

bors commented Sep 16, 2022

bors commented Sep 16, 2022