Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
wants to merge 5 commits into from

Conversation

mousetail
Copy link

@mousetail mousetail commented May 3, 2022

It seems like resolver = 2 is just a basic requirement to build any package with dependencies. To make the examples work it's needed. Apparently there is work to make it default (rust-lang/rust#90148) but right now it's required.

What does this PR try to resolve?

The examples in the documentation about workspaces don't work in the latest edition of rust. This would have saved me many hours of debugging.

Ideally there would also be a description of what the option actually does but I don't really understand that myself.

How should we test and review this PR?

It's a documentation change. Check if you think the information is useful.

Additional information

Relevant links:

It seems like `resolver = 2` is just a basic requirement to build any package with dependencies. To make the examples work it's needed. Apparently there is work to make it default (rust-lang/rust#90148) but right now it's required.
@rust-highfive
Copy link

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 3, 2022
@epage epage changed the title Add "resolver = 2" option to all relavent code samples Add "resolver = 2" option to workspace manifest examples May 3, 2022
@epage
Copy link
Contributor

epage commented May 3, 2022

FYI I updated the PR description to more closely match what this does. When I read it, I assumed it was going to apply to all manifest examples, even if the edition is set.

@ehuss ehuss added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 23, 2022
epage added a commit to epage/cargo that referenced this pull request Sep 13, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 13, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 13, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 13, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 13, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 16, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 16, 2022
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.
epage added a commit to epage/cargo that referenced this pull request Sep 16, 2022
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.
bors added a commit that referenced this pull request Sep 16, 2022
docs(ref): Clarify workspace settings

### 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.
-->
<!-- homu-ignore:end -->
@bors
Copy link
Contributor

bors commented Sep 16, 2022

☔ The latest upstream changes (presumably #11082) made this pull request unmergeable. Please resolve the merge conflicts.

weihanglo pushed a commit to weihanglo/cargo that referenced this pull request Sep 16, 2022
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.
@weihanglo
Copy link
Member

Ping @mousetail. Just checking in to see if you are still interested in working on this, or if you had any questions.

By the way, workspace.md has got a content re-org recently. You may need to resolve some conflicts before proceeding.

Hezuikn pushed a commit to Hezuikn/cargo that referenced this pull request Sep 22, 2022
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.
Hezuikn pushed a commit to Hezuikn/cargo that referenced this pull request Sep 22, 2022
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.
Hezuikn pushed a commit to Hezuikn/cargo that referenced this pull request Sep 22, 2022
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.
Comment on lines 105 to 110
The [`resolver`] key effects how a package that is depended on in multiple
ways with different features are resolved. Some libraries depend on it being
set to 2.

An empty `[workspace]` table can be used with a `[package]` to conveniently
create a workspace with the package and all of its path dependencies.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't quite fit within the current section

Maybe we should move this into the "virtual workspace" section and only update that example?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this paragraph, seems like this concept is explained well enough in the virtual workspace section

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The focus of my concern wasn't so much the duplication of information about virtual workspaces but that we are in the section about members and exclude keys and introducing the resolver key as if it belongs in that section. We then include the resolver key in each further section. I get the point of including the resolver key in each subsequent section, to try to remind people to use it, but it doesn't quite fit seeing an unexplained key and one that is only relevant when its a virtual workspace. This is why I was recommending to make this entire PR only touch the virtual workspace section.

This PR does not have to do all of the lifting for helping users. We also have #10910.

Comment on lines +110 to +111
### Workspace selection

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove

@@ -128,6 +136,7 @@ used:
[workspace]
members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
default-members = ["path/to/member2", "path/to/member3/foo"]
resolver = "2"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove

@@ -225,6 +234,7 @@ configuration in `Cargo.toml`. For example:
```toml
[workspace]
members = ["member1", "member2"]
resolver = "2"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove

@@ -78,6 +83,7 @@ version = "0.1.0" # the current version, obeying semver
authors = ["Alice <[email protected]>", "Bob <[email protected]>"]
```


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove

Comment on lines +74 to +76
The [`resolver`] key here effects how a package that is depended on in multiple
ways with different features are resolved. Some libraries depend on it being
set to 2.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd recommend shifting the focus to fit within this section. We delegate explanation of the field to the resolver page.

Something like

Without a root package to fall back on, the [`resolver`] field should be set in the `[workspace]` table.

(at first I was worried this was too strong of a recommendation but it is roughly what the resolver page says)

@weihanglo
Copy link
Member

Ping @mousetail. Just checking in to see if you are still interested in working on this doc improvement. Feel free to ask any question here or on Zuilp.

@ehuss
Copy link
Contributor

ehuss commented May 9, 2023

I'm going to close due to inactivity. I think it might be good to more clearly recommend setting the resolver field in a workspace, but I'm not sure this PR quite hit the right balance of focus. I'd also mention #10112 might be a stronger indicator than assuming people read the documentation.

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants