The future incompatibility report warning is scary and confusing

[grahamc]

Problem

Today I got this warning:

warning: the following packages contain code that will be rejected by a future version of Rust: num-bigint-dig v0.8.4, sqlx-postgres v0.7.4
note: to see what the problems were, use the option --future-incompat-report, or run cargo report future-incompatibilities --id 1

and my immediate reaction was: wtf? I thought Rust didn't make breaking changes like that, and that these sorts of changes were gated on editions.

Of course, I didn't even see the second line about seeing the report at first. And when I did, I assumed -- since Rust makes these changes so infrequently -- that "id 1" was like a globally unique ID, and not just the first one made on my system.

I was also surprised that there was no URL or something to click for greater context about the whole thing.

Proposed Solution

I don't know, I just wanted to share that I had a pretty visceral reaction to what turned out to be approximately nothing I needed to worry about.

• Maybe making the message say "a future edition" instead of "a future version".
• Maybe making the "note" part of the initial log message would help.

Notes

I always feel really safe in my investment into Rust as a platform to build my software on. It's basically never let me down. This warning made me wonder if I was going to be disappointed for the first time in this way. It turns out I don't think I will be, but I was kind of shaken there for a second.

Thank you for having such an amazing ecosystem where this kind of "bug report" / "feature request" is even plausibly relevant, the bar is really high.

[epage]

I agree that without existing context on this, this can be confusing

I was also surprised that there was no URL or something to click for greater context about the whole thing.

Cargo's URL for these is https://doc.rust-lang.org/cargo/reference/future-incompat-report.html

I feel like that doesn't provide some of that basic context that would help users. Also unsure how much we should try to fit into the message vs leave for the website.

and my immediate reaction was: wtf? I thought Rust didn't make breaking changes like that, and that these sorts of changes were gated on editions.

...

Proposed Solution

...

Maybe making the message say "a future edition" instead of "a future version".

There are some specific cases where Rust may make a breaking change outside of editions which is what this report is for. iirc the cases are if a library is relying on a bug or a change is needed to fix a soundness issue. This would be good context to add to that previous link.

I assumed that -- since Rust makes these changes so infrequently that "id 1" was like a globally unique ID, and not just the first one made on my system.

If we consolidated our future incompat reporting system with our in-work structured logging, we could shift the IDs to be the Run IDs of commands more generally which could help clarify that the ID is not globally unique. For example, the run IDs currently look something like 20251215T151902794Z-f825deefde117ec1. CC @weihanglo

Maybe making the "note" part of the initial log message would help.

We're in transition from our own diagnostics to using the same renderer as rustc. As a compromise, we made the note a "sub-diagnostic" in rustc parlance which put it on its own line like that. If we switched it to a message on the main diagnostic, it would render like

warning: the following packages contain code that will be rejected by a future version of Rust: num-bigint-dig v0.8.4, sqlx-postgres v0.7.4
  |
  |= note: to see what the problems were, use the option `--future-incompat-report`,
     or run `cargo report future-incompatibilities --id 1`

I initially held off as we further iterate on the new diagnostics

• for more self-consistency until we use the new renderer
• as we better explore the distinction between attaching content to a diagnostic vs using a sub-diagnostic.

[weihanglo]

I feel like that doesn't provide some of that basic context that would help users. Also unsure how much we should try to fit into the message vs leave for the website.

Maybe on the Cargo book side we should add more context, and add a note to the Cargo diagnostic (with clickable link):

note: for more on future incompatibility report, see <clickable-link>

Here are some materials we may want to use to improve our doc: https://rust-lang.github.io/rfcs/2834-cargo-report-future-incompat.html#guide-level-explanation.

If we consolidated our future incompat reporting system with our in-work structured logging, we could shift the IDs to be the Run IDs of commands more generally which could help clarify that the ID is not globally unique. For example, the run IDs currently look something like 20251215T151902794Z-f825deefde117ec1. CC @weihanglo

Yeah reorganizing future-incompat-report is under my radar. Thanks for the ping!