Find a way to detect API breakage.

[mahkoh]

Given that the current rust ecosystem tries very hard to force everyone to use semver, and given that rust code breaks the API easily, this is very important.

Some easy but surprising ways to break the API:

• Adding a field to a struct.
• Changing a struct from Copy to NoCopy (same with Send, Sync, etc.)
• Adding a variant to an enum.
• Adding a public method to a type (consider extension traits)
• Adding a method to a trait (consider Conflicting method names in the same trait hierachy can only ever be called with UFCS syntax #17151)

Therefore rustc needs to have something like this:

rustc --record-api out.json lib_old.rs

stores api information in out.json

rustc --compare-api out.json lib_new.rs

Checks if the new api is compatible with the old one.

[aturon]

We had an extensive discussion at the last work week about what exactly should count as a breaking change. I hope to write this up in a more formal way and propose it as official guidelines for semver/stability attributes.

Automating these checks via a tool would be amazing.

[huonw]

Adding a field to a struct.

Adding a public field.

[thestinger]

Adding a private field is also a breaking change if it had no private fields before. Adding a public field is only a breakage change if it had no private fields before.

[mahkoh]

Has anything happened here? Another one:

• Making a previously non-panicking function panic.

[eddyb]

@mahkoh That affects ABI (nounwind and emitting landing pads), but why does it impact API compatibility?
All code that previously compiled against a library with non-panicking functions, should still compile when those functions are changed to panic.

[mahkoh]

You cannot call panicking functions in destructors if your program depends on destructors running.

[mahkoh]

This might also cause UB if you previously counted on a function not panicking while writing unsafe code.

[huonw]

A reliable program cannot depend on destructors running. E.g. the operating system can just kill it outright due to OOM, at essentially any time.

[mahkoh]

This is correct but some people do rely on it. See for example this thread #19245

Those who defend unwinding sometimes argue that it is essential for certain programs such as Servo which relies on unwinding. But the process will simply abort if destructors fail during unwinding.

[mahkoh]

It's actually worse than that. Changing a function from non-panicking to panicking can cause UB in previously completely safe code. Consider the following module written in rust and called from C code:

#[no_mangle]
pub extern fn hello_rust() -> *const u8 {
    "Hello, world!\0".as_ptr()
}

If as_ptr introduces a panicking case, then this will cause UB without having to use unsafe.

[eddyb]

@mahkoh I think the plan is to catch unwinding and abort at extern "C" boundaries.

[mahkoh]

The more common case is unwinding in unsafe code.

rust/src/libcollections/vec.rs

Line 262 in f3d71be

ptr::copy_nonoverlapping_memory(dst.as_mut_ptr(), ptr, elts);

Changing the conditions under which a function can panic has to be considered a breaking change.

[mahkoh]

rust-lang/rfcs#757 addresses

• Adding a variant to an enum.

[steveklabnik]

I'm pulling a massive triage effort to get us ready for 1.0. As part of this, I'm moving stuff that's wishlist-like to the RFCs repo, as that's where major new things should get discussed/prioritized.

This issue has been moved to the RFCs repo: rust-lang/rfcs#759

[mahkoh]

I believe this should stay here at least until it has been decided what is considered breaking the API.