SemVer: Add section on RPIT capturing

[ehuss]

This adds a section on RPIT capturing, added in Rust 1.82, with a note about how this changes in the 2024 edition.

[rustbot]

r? @epage

rustbot has assigned @epage.
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

[weihanglo]

Not sure why.

---- freshness::rebuild_tests_if_lib_changes stdout ----
running `/home/runner/work/cargo/cargo/target/debug/cargo build`
running `/home/runner/work/cargo/cargo/target/debug/cargo test`
running `/home/runner/work/cargo/cargo/target/debug/cargo build -v`
running `/home/runner/work/cargo/cargo/target/debug/cargo test -v`
thread 'freshness::rebuild_tests_if_lib_changes' panicked at tests/testsuite/freshness.rs:633:10:

---- expected: tests/testsuite/freshness.rs:623:27
++++ actual:   stderr
   1    1 | [DIRTY] foo v0.0.1 ([ROOT]/foo): the dependency foo was rebuilt ([TIME_DIFF_AFTER_LAST_BUILD])
   2    2 | [COMPILING] foo v0.0.1 ([ROOT]/foo)
   3    3 | [RUNNING] `rustc --crate-name foo [..]
   4      - [RUNNING] `rustc --crate-name foo [..]
   5    4 | error[E0425]: cannot find function `foo` in crate `foo`
        5 +  --> tests/foo.rs:4:34
   6    6 | ...
   7    7 | [ERROR] could not compile `foo` (test "foo") due to 1 previous error
   8    8 | ...∅

[weihanglo]

Looks great!

cc @obi1kenobi though I've already noticed obi1kenobi/cargo-semver-checks#815.

[obi1kenobi]

Very nice! I look forward to being able to cite this new section in cargo-semver-checks lints :)

Thanks for the tag @weihanglo!

[obi1kenobi]

I believe this might not be true for functions in non-sealed traits. If the trait's function definition changes the RPIT captures, I expect implementations of the trait have to be updated to match.

[weihanglo]

Hmm… sounds very likely. Could you give an example of it?

[obi1kenobi]

Ah it seems use syntax in RPIT in traits isn't supported yet, so I can't give you a playground example.

But here's proof from a related thread: rust-lang/rust#132795

It shows this example:

trait TypeParam<T> {
    fn test() -> impl Sized;
}
// Indirectly capturing a lifetime param through a type param substitution.
impl<'a> TypeParam<&'a ()> for i32 {
    fn test() -> impl Sized + use<> {}
    //~^ WARN impl trait in impl method captures fewer lifetimes than in trait
}

and states that the impl is a valid refinement of the trait.

But if it's a refinement, that means not all implementations of the trait have to adhere to it — it's a stricter interface than what the trait requires.

Therefore, applying this to our question at hand about removing generics from use<>: If the trait were edited to go from (implicitly) fn test() -> impl Sized + use<T> to fn test() -> impl Sized + use<>, that would be a breaking change. The impls that had applied the refinement would continue to work, and impls that didn't refine in this way would be broken.

[obi1kenobi]

So to summarize, the statement is accurate as written so long as use<> in RPITIT isn't supported. But it sounds like that limitation is of a temporary "work in progress" nature, so it's probably a good idea to make the semver reference a bit more future-proof.

I think the accurate statement here is "major change in RPIT in traits unless the trait is sealed, minor change otherwise."

[ehuss]

I'm not quite following here. Since RPITIT is not stabilized, I would prefer to not refer to it or document its behavior. When it is stabilized, we can update the documentation to say that it is a major change to change which generics are captured in RPITIT unless the trait is sealed. (Depending on if the design of RPITIT changes.) Does that make sense?

[obi1kenobi]

Oh, sorry. My statement was not intended for inclusion in this document. It was merely intended as a summary of my understanding of Rust's present and plausible future rules here.

If you're sure we can remember to follow up on this section when use<> in RPITIT is stabilized, then I'm fine with either wording here. Otherwise, it may be wise to consider slightly more defensive wording here that explicitly excludes RPIT in traits.

I just wanted to raise this for your consideration — it's your call to make and I'm happy with whatever you think is best.

[weihanglo]

I am not sure how to make sure to remember updating the doc, but at least now we have three people aware of it. I think it's good to move forward.

Thanks folks for the discussion!
(I have more understanding for generics capturing after this 😆)

[obi1kenobi]

A thought: would it be worth adding an example, or even just mentioning in a sentence or two that use<> syntax can also be used to capture type parameters, not just lifetimes? That wasn't immediately obvious to me when I first heard about this new language feature.

[ehuss]

Sure, I added a note here. I don't think type and const generics have any impact here because you cannot change them. I generally would like to avoid using this space for teaching how the language works, and that's why there are links to the reference and edition guide which do elaborate on how it works.

[weihanglo]

I am not sure how to make sure to remember updating the doc, but at least now we have three people aware of it. I think it's good to move forward.

Thanks folks for the discussion!
(I have more understanding for generics capturing after this 😆)