Shower thought: docs.rs should integrate changelogs somehow

95 points AdmiralQuokka 18 comments

I'm cargo updateing right now, and hunting down changelogs. I'm tired of updating libraries that don't have a changelog at all. Even if there is one, manually scraping together the changes in the range I'm updating is annoying.

I think changelogs should be first-class citizens in the Rust documentation tooling. For example, it would be super cool if you could select a range of versions on docs.rs and it shows you what has happened since then. Comparing across major version would contain breaking changes and maybe a migration guide. Comparing minor versions would be possible as well, showing you what new features you can use after updating.

To achieve that, cargo would have to be opinionated about the format of your changelog. It needs to be broken down into (at least) breaking changes, features and fixes. That way these three categories can be merged across a range of versions, in case users are only interested in breaking changes.

Agressive hot take: Cargo should eventually refuse to publish a new major version without a changelog that contains some breaking changes section. How am I supposed to update a library if there is zero documentation about what changed? (I guess that might be against Rust's stability guarantee. Just wanted to throw the opinion out there.)

What do you think?

Another shower thought: There should be a clippy lint "group" for libraries that can be enabled with one line in Cargo.toml (lints.clippy.library = "warn"). This would enable some allow-by-default lints for library best practices. For example, the lint that every public item should be documented.

If some of that already exists and I just don't know about it, I hope I have rage baited someone into telling me about it :)