Document how to use rust-toolchain.toml to avoid breaking changes (e.g. in CI)

[lgarron]

I've had Clippy suddenly start to fail in GitHub Actions for me in multiple ways over the last year.

If Clippy was still used as a crate, I'd just pin it as a dependency and run https://crates.io/crates/cargo-run-bin/1.7.2

However, that's unfortunately not possible and I found it far from obvious what to do instead. My understanding is that pinning it using rust-toolchain.toml like this is the "correct" way to avoid breaking changes in CI. This took me some time and research (and personal help from a Rust expert) to figure out and I'd like to save others the trouble by documenting it.

changelog: none

Note that this issue talks about CI because that's that's a common forcing function for consistent linting, but it applies to local invocations as well.¹ I think this is much better to document on the installation page instead of the CI pages specifically.

Footnotes

1. For example, I collaborate on a project where another team member regularly touches just the non-Rust code in the repo but runs all project tests locally before pushing. These local tests runs have failed for all sorts of ecosystem issues in the past, and that's never a good experience. So it's important for tools like Clippy to be stable even outside of CI, and I would personally want to know about how to do this when learning how to install Clippy for the first time. ↩

[rustbot]

r? @flip1995

rustbot has assigned @flip1995.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[samueltardieu]

This is not specific to Clippy: the compiler itself introduces new lints and warnings. For example, in Rust 1.88, transmuting between a char and a 32 bit integer will trigger a warning.

[lgarron]

This is not specific to Clippy: the compiler itself introduces new lints and warnings. For example, in Rust 1.88, transmuting between a char and a 32 bit integer will trigger a warning.

I guess that's fair. In that case, if one looking for consistent code warnings then pinning like this is even more important?

[samueltardieu]

Yes, but does it belong to Clippy documentation when this is not Clippy specific?

[lgarron]

Yes, but does it belong to Clippy documentation when this is not Clippy specific?

I would strongly argue yes. Absolutely.

• If I am new to an ecosystem and want to enforce code quality, I will look for a linter.
• I would like to configure that linter so that it's as helpful as possible. In particular, it needs to return consistent results so that it can actually be used to enforce code quality on the code base.
• For Rust, clippy is the de facto linter.

The fact that the Rust compiler also performs some Clippy-like linting is something that people only know if they already familiar with the ecosystem.

Everyone has to learn that for the first time, and I think the Clippy installation instructions are the perfect place to say "if you want consistent linting, here's what you need to know/do". If this information had been there when I first started using Clippy, I would have learned about the proper use of rust-toolchain.toml months early.

I've designed this PR to convey "if you're looking for consistent linting you'll probably actually want an entire pinned toolchain", but please let me know if I could change it to be more clear.

I think it's reasonable to argue that someone can stitch the configuration together if you just give them links to other places, but at least in my case I would probably have missed the components = ["clippy"] line. If you leave it out, you can easily end up in a "works on my machine" state that will cause debugging later. Since the entire snippet is really short (and linked to more information for context), I think it's rather valuable to include.