Skip to content

doc: Recommend tracking Cargo.lock with rust-toolchain files #3054

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.

Sign up for GitHub

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

Merged
rbtcollins merged 1 commit into from
Jan 17, 2023
+3 −1
Merged

doc: Recommend tracking Cargo.lock with rust-toolchain files #3054

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/src/overrides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,9 @@ that uses the new TOML encoding in the `rust-toolchain` file. You need to upgrad
`rustup` to 1.23.0+.

The `rust-toolchain.toml`/`rust-toolchain` files are suitable to check in to
Copy link
Copy Markdown
Contributor

@rbtcollins rbtcollins Jan 15, 2023

Choose a reason for hiding this comment

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

I'm not sure what we mean by 'suitable to check into source control' here.

We probably need to do a bit of clarification / nuance around rust-toolchain files, since when used without care a bunch of friction - like this PR talks about - turns up.

I've taken to recommending folk don't use rust-toolchain in fact because of the number of touch points - things like automatically installing a toolchain in a docker build which errors (because we don't fall back to copy, which is a choice I still support), or the fact that putting a symbolic toolchain like 'stable' in a rust-toolchain file doesn't provide any sort of state-of-the-world benefit. Cargo's rust-version header is IMO sufficient and better for most use cases.

That said, it is a feature we support, and it is true that a toolchain file that pins to a specific concrete version will cause friction for developers when dependencies have an MSRV above the rust-toolchains version.

I think documenting the friction is a decent starting point, though I do wonder if we should go further and have cargo use a fixed toolchain as a constraint in dependency updates (checking the msrv in the dependencies Cargo.toml).

Thats a separate conversation though.

source control.
source control. If that's done, `Cargo.lock` should probably be tracked too if
the toolchain is pinned to a specific release, to avoid potential compatibility
issues with dependencies.

The toolchains named in these files have a more restricted form than `rustup`
toolchains generally, and may only contain the names of the three release
Expand Down
⚡