docs(workspace): add recommended structure to members field#17166
docs(workspace): add recommended structure to members field#17166raushan728 wants to merge 1 commit into
Conversation
rustbot
added
A-documenting-cargo-itself
|
r? @epage rustbot has assigned @epage. Use Why was this reviewer chosen?The reviewer was selected based on:
|
raushan728
changed the title
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
| typical filename glob patterns like `*` and `?`. | ||
|
|
||
| ### Recommended structure | ||
|
|
||
| It is recommended to keep all member packages in a flat directory (commonly `crates/`) and use a glob pattern for the `members` field, e.g. `members = ["crates/*"]`. This makes it easy to add new members with `cargo new` / `cargo init` without editing the root manifest. | ||
|
|
||
| The `exclude` key can be used to prevent paths from being included in a |
There was a problem hiding this comment.
The framing on this feels a bit strong and "it is recommended" is passive voice.
I'm hoping mirroring what we do at https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#version-metadata would help
There was a problem hiding this comment.
I've updated. could you check if the line wrapping good now?
Adds a recommendation block advising users to keep workspace members in a flat directory and use glob patterns.
|
This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed. Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers. |
raushan728
changed the title
| **Recommendation:** Keep all member packages in a flat directory (commonly `crates/`) | ||
| and use a glob pattern for the `members` field, e.g. | ||
| `members = ["crates/*"]`. This makes it easy to add new members with | ||
| `cargo new` / `cargo init` without editing the root manifest. |
There was a problem hiding this comment.
People may edit the list directly. Likely better to focus on the underlying concern:
| **Recommendation:** Keep all member packages in a flat directory (commonly `crates/`) | |
| and use a glob pattern for the `members` field, e.g. | |
| `members = ["crates/*"]`. This makes it easy to add new members with | |
| `cargo new` / `cargo init` without editing the root manifest. | |
| **Recommendation:** Keep all member packages in a flat directory (commonly `crates/`) | |
| and use a glob pattern for the `members` field, e.g. | |
| `members = ["crates/*"]`. This minimizes churn in maintaining the `members` list. |
I'd like to include more of the thoughts from https://matklad.github.io/2021/08/22/large-rust-workspaces.html but I feel like it would overly bloat this and it might be easier to just keep this simple.
The reasons there:
- a flat list matches the flat nature of namespaces (for now)
- flat lists are easier to scan
- no perfect hierarchy
The benefit you are highlighting is also a more clear cut technical one than these which makes it less up for debate.
4 participants
Closes #11234