Following the existing wording practice in this section makes this hard to read. This makes it sound like we are editing existing hard errors, like there message.

There are perfectly good reasons to add new hard errors. I feel like this isn't doing a good job explaining when to do so or not but making it sound like there is a blanket reason we should never do them.

It's hard for me to think of a set of criteria. Just revised the wording a bit, making it less like we don't accept errors.

I can't quite place the issue I have with the new wording. I wonder if this is worth covering. We have a good treatment on this problem when it comes to unstable features. The case we ran into here was an odd mixture of things and a case where we likely wouldn't have done something different anyways.

The case we ran into here was an odd mixture of things and a case where we likely wouldn't have done something different anyways.

Maybe I have misunderstood.

From my point of view what happened here was a breach of Rust's stability guarantees. It was a foreseeable consequence of adding a new warning that would need people to add suppressions. Those suppressions would then, inevitably, need to be tolerated without complaint by older Rust versions. Note that the message that needs suppressing even advises using the syntax which certain range of versions of Rust would reject., rather than the one which is tolerated by all Rust versions.

It doesn't appear that there was anything that I could sensibly have done differently (other than perhaps to take a completely different design approach in my package) to detect and avoid this.

I do have very thorough tests, but it didn't occur to me that I might need to test intermediate versions of Rust. The Rust stability guarantee ought to mean that testing with my MSRV (1.56 in this case) would be enough.

Now, I understand that mistakes happen. Thanks to @zydou for trying to help avoid future similar mistakes. I really appreciate it. But:

It sounds like @epage is saying that what happened here is fine, was not a mistake, and in a similar situation you'd do the same again. I do hope I have misunderstood.

From my point of view what happened here was a breach of Rust's stability guarantees.

The "standard" stabilization process for Cargo has been to take a Cargo.toml field that would be considered "unused", have a period of time where using it is a hard error, and then after that it is processed according to a specific set of rules or it hard errors. We followed that model here though we didn't have the "unused" warnings.

Like I alluded to earlier, we have recently formalized alternative models to avoid the hard errors that force an MSRV bump but they only apply in specific circumstances. We currently have no process to help people to catch this broken phase except for where we have "unused" warnings and people notice them (e.g. I never look at the non-fatal output from my MSRV runs).

The only violations of stability guarantees were that we took : prefix link metadata and turned them into hard errors and you can no longer set the check-cfg link metadata key. The former we did very consciously as a team. The latter was from before we had fully considered and decided to avoid conflicting with link metadata keys and was grandfathered in and to avoid this is why we did the :: change.

It was a foreseeable consequence

That is a view from hindsight and is unfair to the developers involved. Please be empathetic to developers who are working with the limited perspective they have during development.

Check-cfg had been in development for a long time but had stagnated. During that lull, we had problem with evolving build script syntax and found a unlikely corner case that we could break compatibility on (link metadata that starts with :;) that we used as an out to make it so we could add new build script directives (technically, adding check-cfg, broke compatiblity as it took a potential link metadata name). We did blanket documentation updates. Check-cfg was then polished up and stabilized by someone seeing and acting on this new documented syntax. We considered MSRV through this process but had overlooked : vs :: in the documentation / messages. Some of that get polished up as this rode the train to being on stable.

It sounds like @epage is saying that what happened here is fine, was not a mistake, and in a similar situation you'd do the same again. I do hope I have misunderstood.

I don't think this proposed documentation change would have made a difference if it had been in place. We already have been taking MSRV into account in our designs recently and had discussions during the stabilization of both halves of this related to MSRV. Its a hard trade off to decide whether unsupported build script directives should be an error or a warning but starting with an error is the safest route.

This specific situation was partially from two features being developed in parallel without a good opportunity to reflect on how they interacted which is hard to do outside of hindsight and this documentation change does not address.