Document that adding #[non_exhaustive] on existing items is breaking.

[obi1kenobi]

What does this PR try to resolve?

Adding #[non_exhaustive] to an existing struct, enum, or variant is almost always a breaking change and requires a major version bump for semver purposes. This PR adds a section to the semver reference page that describes this and provides examples showing how #[non_exhaustive] can break code.

Additional information

Adding #[non_exhaustive] to a unit struct currently has no effect on whether that struct can be constructed in downstream crates. This is inconsistent with the behavior of #[non_exhaustive] on unit enum variants, which may not be constructed outside their own crate. This might be due to a similar underlying cause as: rust-lang/rust#78586

The confusing "variant is private" error messages for non-exhaustive unit and tuple variants are a known issue tracked in: rust-lang/rust#82788

Checking for the struct portion of this semver rule is done in: obi1kenobi/cargo-semver-checks#4

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) soon.

Please see the contribution instructions for more information.

[ehuss]

Thanks!

[ehuss]

This seems to be worded a little strongly. Pedantically this isn't correct, as it is possible pattern match without _. For example:

match std::num::IntErrorKind::InvalidDigit {
    // Identifier patterns are exhaustive.
    x => {}
}

match (1, std::num::IntErrorKind::InvalidDigit) {
    // Within another type, other patterns can count for exhaustiveness.
    (x, ..) => {}
}

I would just say something like "Pattern matching on non-exhaustive struct variants requires .. and matching on enums does not count towards exhaustiveness."

[ehuss]

BTW, a new rule is being added in 1.65 that non-exhaustive enums cannot be casted with as (see rust-lang/reference#1249).

I'm reluctant to try to repeat the rules in this document since it will be difficult to keep in sync, or there may be subtle differences. However, this is useful information so it should probably be ok to repeat them here.

[ehuss]

I pushed a change with the suggestions I had for clarifying what changes when non_exhaustive is added.

Asking for another reviewer just to make sure that the wording here looks good to someone else.

@rustbot ready

r? weihanglo

[obi1kenobi]

Thanks for taking this over, sorry for dropping the ball on it! The wording looks great to me.

[weihanglo]

Looks great to me. Easy to catch up.

@bors r+

[bors]

📌 Commit f18f7f1 has been approved by weihanglo

It is now in the queue for this repository.

[bors]

⌛ Testing commit f18f7f1 with merge c455de9...

[bors]

☀️ Test successful - checks-actions
Approved by: weihanglo
Pushing c455de9 to master...