Create an `apitest` tool for stabilizing core interfaces.

[brson]

This would be a tool to guarantee stability and backwards-compatibility of core library interfaces. It takes a rust source file (the 'spec') that declares the item's and pub uses in core, without implementation. It then parses both the spec and the library and compares them. Any mismatches are errors. Report various metrics about stable/unstable APIs.

The goal is to make it very difficult to change interfaces that are stable. The downside is that you have to ultimately redeclare all of core.

[brson]

I'd be interested to hear other ideas on this topic.

[thestinger]

This would be neat, there are a lot of bits of the container interfaces that definitely aren't ever going to change (everything in Container/Map/Set that isn't an iterator).

I'd like to be able to mark them as stable, even if it was somewhat painful/redundant.

[brson]

After thinking about this further let's adopt node's stability levels. We can use attributes to tag items. The tool then would periodically extract the public item signatures, exporting them to a file or comparing them against a file. Approved API changes would then need to use the tool to regenerate the signatures file and check it in. Depending on how elaborate you want the tool's reporting to be there could be overlap in functionality with rustdoc.

[brson]

The compiler can also warn about using unstable, experimented, deprecated apis.

[brson]

If there is already a #[deprecated] attribute let's fold that in to the stability levels attributes.

[brson]

If we wanted to validate test coverage for stable features this would probably be the tool for that as well.

[brson]

I've started work on this in my apilock branch.

[metajack]

visiting for triage. nothing to add.

[huonw]

Triage: we now have semi-supported stability attributes, nothing else to add.

[alexcrichton]

cc rust-lang/cargo#374

[steveklabnik]

Triage: we have stability attributes for this purpose, and while it's not quite the same thing, it's working at the moment. I feel like this may be a conceptual dup of another issue relating to stability detection, but I'm not sure, so leaving it open for now.

[steveklabnik]

Revisiting a few months later, we have a good story with how we ensure lack of breakage here, through stability attributes. So giving this a close.