Protecting the Rust standard library from accidental breakage
7 points by predrag
7 points by predrag
Very cool! Treating unstable items as #[doc(hidden)] is such a clever trick, I never would have thought of that! cargo-semver-checks has cemented itself in the Rust ecosystem as such a reliable and valuable tool, congratulations!
Thank you for being a fan and reading the post!
Also, this is actually still only half the story! There will probably be more blog posts :)
To make this work, I had to work out a principled model for how re-exports interact with stability and doc(hidden). In discussing this with other Rustaceans, it turns out that this model is more complete and better-behaved than what rustc / rustdoc use internally. The rustc/rustdoc current internal model is a bit ... footgunny. For example, folks have accidentally stabilized things without anyone noticing 😬
So now we have a proposal to adopt the cargo-semver-checks model in rustc + rustdoc: https://github.com/rust-lang/rust/issues/161153
Classic "fix one thing, find 3 more things to fix" story. One thing is for sure, I'm not likely to be bored or out of things to work on anytime soon!
How does this interact with items with both a stability guarantee such as #[stable(feature = "rust1", since = "1.0.0")] and #[doc(hidden)] (such as std::vec::from_elem) are these allowed to be broken?
Yes, cargo-semver-checks would not report breakage if that item was removed.
As far as I can tell, std::vec::from_elem powers the macro expansion of vec![value; N] and is explicitly #[doc(hidden)] and placed in a section labeled "internal." One won't find it in the docs of its module. So this case seems to fall into the "internal code that is forced to be pub/stable due to macro-expanded code being inside downstream crates" exception and therefore carries no SemVer guarantee of stability.
If at some point that method was stable but not #[doc(hidden)] and later became so, cargo-semver-checks would consider that moment the point where breakage happened.