Checking semver in the presence of doc(hidden) items

submited by
Style Pass
2023-11-18 15:30:05

cargo-semver-checks v0.25 squashes nearly all bugs related to doc(hidden) items — its most common source of false-positives. What does doc(hidden) mean in Rust, and why was handling it correctly so hard?

In today's post, we dig into how "public API" isn't the same thing as "all pub items," and why that caused headaches for cargo-semver-checks users prior to v0.25. Resolving those headaches is now as simple as upgrading to the latest cargo-semver-checks!

The #[doc(hidden)] attribute is a way to mark pub items exported by a crate as "not public API" and therefore exempt from semver obligations. It's commonly used — any Rust project likely has at least one dependency containing public doc(hidden) items.

Prior to v0.25, doc(hidden) could be a huge problem for cargo-semver-checks users. Our study of semver compliance in the top 1000 Rust crates showed it was the source of over 60% of our false-positives. The study ended up discarding nearly half (46.6%) of all issues reported by cargo-semver-checks as doc(hidden) false-positives alone. To put it mildly: not great. Thankfully, these false-positives were not evenly distributed: most crates had zero or very few and were able to use cargo-semver-checks without issue, while a minority of crates were doc(hidden) Georg and cargo-semver-checks was practically unusable for them. The next section offers intuition for why this is the case. For crates that heavily rely on doc(hidden), using cargo-semver-checks was a frustrating experience whenever the hidden items changed.

cargo-semver-checks v0.25 addresses this problem. A tiny handful of rare edge cases remains unsolved since it first requires another feature: the ability to detect whether, and to what degree, a trait is sealed. As readers of this blog know, that's also more complex than it may seem at a glance. Fortunately, real-world data shows those cases are extremely rare in practice — and we have a path toward handling them correctly in the future. More on this in future posts! It's not every day that one eliminates over 60% of outstanding bugs! 🎉

Leave a Comment